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

[Jeff Newmiller]

Wow. Did you consider reading the Posting Guide, which indicates that this is not the right list for these questions? Please follow up in the right mailing list, but maybe this will get you started.

Your missive is full of value judgements... I can only suppose that is what you get for believing every random post you see on the Internet.

My first suggestion is to remember that there are many perspectives on what is the "right" way to construct packages, but like it or not they all have to lead to a result that conforms to the Writing R Extensions (WRE) document maintained by R Core... stop asking what that means and read that first. Yes it is long, but it IS the reference.

That said, you may find that using roxygen  can reduce some busywork (some hold the opinion that the more traditional approach leads to more useful documentation).  If the CONTRIBUTED PACKAGE roxygen changes how it works over time... well, read its documentation, and keep in mind that whatever is does is only window dressing intended to generate valid files for R to work with according to WRE. Stop depending on blog posts... when they help, great... but when they don't, go to the official documentation.

Finally, Rmd is usable for vignettes, but not any other help files. Rd has its own syntax that is not latex and not Rmd, because it is translated to various other formats as needed in a more comprehensive way than Rmd files are handled.

As for examples... there are thousands, and "good" is much too subjective to sort by. If you want examples of using roxygen, look for the dependency in CRAN.

On February 17, 2019 9:50:31 AM PST, Ivo Welch <ivo.welch using gmail.com> wrote:
>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]]
>
>______________________________________________
>R-help using r-project.org mailing list -- To UNSUBSCRIBE and more, see
>https://stat.ethz.ch/mailman/listinfo/r-help
>PLEASE do read the posting guide
>http://www.R-project.org/posting-guide.html
>and provide commented, minimal, self-contained, reproducible code.

-- 
Sent from my phone. Please excuse my brevity.