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

[Bert Gunter]

This is off topic for this list. Post to r-package-devel for questions
about writing r packages, package docs, etc. Note especially the use of
namespaces to avoid name clashes.

-- Bert

Bert Gunter

"The trouble with having an open mind is that people keep coming along and
sticking things into it."
-- Opus (aka Berkeley Breathed in his "Bloom County" comic strip )


On Sun, Feb 17, 2019 at 11:27 AM 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.
>

	[[alternative HTML version deleted]]