Introduce semantics-aware parsing of documentation

[dgkf]

Status: Allowing time for feedback before release

Instead of reiterating myself here, the best place to see these in action is over in r-dcm/measr#52, which was the impetus for these changes.

That package is quite comprehensive in its documentation, so it gives me some pretty strong confidence that things are working as intended, but nevertheless these changes are substantial and would meaningfully increase the scope of this package and its complexity.

To make sure that I'm not biting off more than I can handle, I think it's best to make sure those changes are going to be satisfactory in use over in measr before rolling them out more broadly.

[danielinteractive]

Hi @dgkf , nice to cross paths again!
While starting work on jmpost I also tried to use roxylint from this feature branch. I have problems to modify the linters, please see here: Genentech/jmpost#460
I still see sentence case warnings for @param and @typed here: https://github.com/Genentech/jmpost/actions/runs/26387358652/job/77668783787 (section "Generate man pages") although I thought I took this linter out...
Maybe I am just missing something?

[dgkf]

Hey @danielinteractive! Great to hear from you. Thanks for trying this out.

After spot checking a few of the warnings, I think this is actually working as intended, but the error messages would need to be a lot more clear and I just don't think I have it in me to maintain something aiming to be this specific.

For example, I saw these lines were throwing warnings. I think they'd need to be restructured like this:

- #' @typed object: DataJoint
- #'   Survival and Longitudinal Data.
+ #' @typed object: `DataJoint`
+ #'   Survival and Longitudinal Data.
- #' @typed x: DataJoint
- #'   Survival and Longitudinal Data.
+ #' @typed x: `DataJoint`
+ #'   Survival and Longitudinal Data.
+ #' @concept Survival
+ #' @concept Survival Data
+ #' @concept Longitudinal
+ #' @concept Longitudinal Data

This treats the object name, DataJoint and respective categories of data as proper nouns so that they don't trip the Sentence Case checks.

This code got pretty hairy and the edge cases started to really pile up. I'm a bit afraid of the scope of trying to maintain this in any sort of rigorous way. I think if there were interest in merging this work, I'd be looking to hand off maintenance of it because I think it is beyond what I'd be able to commit to at the moment.