Learning to Write R Packages (Libraries) with Documentation

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

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

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|

Re: Learning to Write R Packages (Libraries) with Documentation

Bert Gunter-2
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 <[hidden email]> 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]]
>
> ______________________________________________
> [hidden email] 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]]

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|

Re: Learning to Write R Packages (Libraries) with Documentation

Bert Gunter-2
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 <[hidden email]> 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 <[hidden email]> 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]]
>>
>> ______________________________________________
>> [hidden email] 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]]

______________________________________________
[hidden email] 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.
Reply | Threaded
Open this post in threaded view
|

Re: Learning to Write R Packages (Libraries) with Documentation

Jeff Newmiller
In reply to this post by ivo welch
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 <[hidden email]> 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]]
>
>______________________________________________
>[hidden email] 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.

______________________________________________
[hidden email] 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.