R help - Feb 2019 - Learning to Write R Packages (Libraries) with Documentation

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]]

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 at 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 at 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]]

Oh, I also would assume that the authoritative, current doc for R package
development is "Writing R Extensions," which of course is part of all
R
distros.

-- 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:35 AM Bert Gunter <bgunter.4567 at gmail.com>
wrote:
> 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 at 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 at 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]]

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 at 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 at 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.