Documentation

[Dasonk]

I just found this via this SO question and it caught my eye. I think this is a nice idea and would make it a lot easier for people to wrap up their useful functions without the overhead of making a package. I've been interested in that idea for a while and one thing I did work on was creating help files for functions that aren't in a package - some of that work is here: https://github.com/Dasonk/flydoc

The solution I have isn't complete - I had a working case of using all of the first comments after the function declaration as the description for the help file but I wasn't in the habit of regularly pushing my commits and ended up losing some of that.

My question for you is how did you envision the 'help documentation' is stored in the users source files? This is your package but I'm interested in helping by forking and getting some of this functionality down but want to know what you had envisioned for that.

[r2evans]

I also saw this package in the same SO question. I'd argue that using roxygen2 would capitalize on a lot of roxy-to-Rd conversions. As far as how to call it, I think something similar to Hadley's devtools would work, where utils::help is masked by devtools:help, which checks to see if it's a devtools-installed help file and falls back to utils::help otherwise.

[klmr]

Like @r2evans, I think the right way is to use established tools – i.e. roxygen2. And yes, I’ll probably copy devtools’ mechanism of hooking into help, although I would have preferred if R provided a direct way of attaching documentation (or other meta data) to a function, instead of having to patch core functions.

With that in mind, I actually like flydoc’s approach of making such meta information accessible at runtime. This won’t be the priority but it’s definitely “nice to have”.

[klmr]

The work for this is currently being done in the branch help. I’m closing this issue for now. Further discussion should take place in #32, or in dedicated issues.

At the time of writing, a rudimentary system of the interactive help works (modulo the issues already reported). I won’t push it into master yet until these issues are resolved.