Adding documentation to modules

[vorpalvorpal]

From https://wahani.github.io/modules/:

If you want proper documentation for your functions or modules you really want a package.

I wonder if this is actually the case. If, on creating a module, we created a 'help' attribute for objects in the module list, we could get any roxygen blocks that immediately precede any function definitions, possibly parse them, and then apply them to the 'help' attribute. A simple function could then look up the 'help' attribute for any object in the module list and print that to the console.

I would personally find that extremely useful.

• Is this functionality that you would consider adding?
• Is there something obvious that I am missing?
• Would you be open to me trying to implement something like this?

I'm not really sure of the mechanics of the displaying things in the normal help window in RStudio/Positron, but that might even be possible as well.

[wahani]

Hi, I haven't been active in R for a while, so took me a while to see this. I would be open to it and would also review your proposition if this is still something you are willing to work on.

Generally speaking I see that modules have their place but it just makes no sense to try to get too many features that are already in the tooling around R-packages. If you want docs, I would propose to put your modules inside a package and use roxygen2 to document the behavior. This should do the trick and is not that much of an overhead. This is what I wanted to encourage with the line in the docs and the reason I never invested much time into the topic other than the option to use comments, e.g.

modules::module({
  some_function <- function() {
    ## This is documentation
    print("This is a function inside a module")
  }
})

that will be used when you print a module.