[R] Learning to Write R Packages (Libraries) with Documentation

[Ivo Welch]

I would like to put together a set of my collected utility functions and
share them internally.  (I don't think they are of any broader interest.)
To do this, I still want to follow good practice.  I am particularly
confused about writing docs.

* for documentation, how do I refer to '@'-type documentation rather than
the latex-like format?  I have read descriptions where both are referred to
as roxygen-type.  I believe that devtools::document() translates the more
convenient @-type into the latex-like format.

* where do I find current good examples of R functions documented properly
with the '@' format.   What should be taken from the function itself (name?
usage?) so as to not repeat myself?

* when I run `document()`, does devtools create a set of documentation
files that I can also easily import by itself into another R session?  I am
asking because I want to put a few functions into my .Rprofile, generate
the documentation, and import it by hand.

* my utility functions currently live in their own environment to avoid
name conflicts ( such as mywork$read.csv <- cmpfun(function()
message("specialized")) ).

  - is keeping function collections in environments a good or bad idea in a
library?
  - will generating a package automatically compile all the functions, so
that I should lose the `cmpfun`s ?
  - to export the functions for others' uses, presumably I should place an
"#` @export" just before the function.

* is there integration between Rmd and R documentation?  Can/should I use
Rmd for writing documentation for my functions and have this become
available through the built-in help system?  Or are the two really separate.

/iaw

PS: Yes, I tried to do my homework.  apparently, the R ecosystem has been
moving fast.  I start reading something, it seems great, but then I find
out that it does not work.  For example, I tried the "Object Documentation"
example from Hadley's book from 2015, but I think it is outdated.  (My
`document()` run seems to want an explicit @name.  Hilary Parker's nice
tutorial is outdated, too, as are many others.  The popular load.Rd example
is already in the latex format. etc.)  where should I look for definitive
documentation for the *current* package writing ecosystem?

	[[alternative HTML version deleted]]