Should `spin` treat roxygen2 function documentation like R code?

[zachary-foster]

I thought it would be awesome to write an R package as a literate programming document, with the code itself producing part of the HTML documentation via spin. One issue I ran into while exploring this possibility is that roxygen2 documentation is treated as Rmarkdown by spin. I know that I can change the value of the doc option when using spin so that the roxygen2 comments are not parsed, but I would like my R files to compile with the default options so things like "compile R notebook" (ctrl + shft + K) work as expected. I also noticed I could comment out the roxygen2 documentation using /* and */, but then it does not show up in the Rmd output.

In short, I would like to produce a document that can be spun using spin's default options in which the roxygen2 function documentation is part of the code chunks. I can see a few ways this could be accomplished:

• change the default value of the doc option. This is probably impractical since it would break a lot of people's code, but I think it is the most elegant solution.
• allow spin option defaults to be read from a header in the "goat hair" R file. This would allow me to specify the doc option value in the R file itself. Maybe something like ##' doc = '^##\\s*' at the start of the file. Another option could be added to specify the regex that corresponds to header lines (in this example '^##'\\s*'). I am willing to try to implement this addition if you are think it is useful.
• Add a new type of commenting similar to /* and */, except that R comments in between are displayed in chunks as R comments rather than being excluded like the comment option does. In my case I would wrap the roxygen2 function documentation with this type of syntax.

I am just getting into using spin so I am sorry if I overlooked some existing functionality that can solve my problem. Thanks for everything!

[yihui]

I can see your problem, but sorry, I don't have a good solution for you, nor do I have much time to think about it at the moment.

[yihui]

You might be interested in this idea I wrote about last year: https://github.com/yihui/rlp

[github-actions[bot]]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.