Re: [Rd] Best practices in developing package: From a single file

[Michael Lawrence]

On Thu, Feb 1, 2018 at 9:20 AM, Gabriel Becker  wrote:

> On Thu, Feb 1, 2018 at 5:24 AM, Lionel Henry  wrote:
>
> > On 31 janv. 2018, at 09:08, Gabriel Becker  wrote:
> >
> > > it *actively discourages* the bits it doesn't directly support.
> >
> > It may be discouraging to include Rd syntax in roxygen docs but only
> > because the LaTeX-like syntax of Rd is burdensome, not because of
> > roxygen. It is still handy to have inlined Rd as a backup and we do
> > use it for the cases where we need finer grained control.
> >
>
> I only somewhat agree with this. Part of it is the Rd specifically, I
> agree, but part of it is just the fact that it is a different syntax at
> all. People who write roxygen documentation tend to think about and write
> it in roxygen, I think. Any switch out to another syntax, thus introducing
> two syntaxes side-by-side, is discouraged by the very fact that they are
> thinking in roxygen comments.
>
> Again, this is a "discouragement", not a disallowing. I know that people
> who care deeply about writing absolutely top notch documentation, and who
> also use roxygen will do the switch when called for, but the path of least
> resistance, i.e. the pattern of behavior that is *encouraged* by roxygen2
> is to not do that, and simply write documentation using only the supported
> roxygen2 tags. I'm not saying this makes the system bad, per se. As I
> pointed out, I use it in many of my packages (and it was my choice to do
> so, not because I inherited code from someone who already did), but
> pretending it doesn't encourage certain types of behavior doesn't seem like
> the right way to go either.
>
>
> >
> > I agree with your sentiment that roxygen encourages writing of
> > documentation for time-constrained users.
> >
>
> I do think it does that, but that was really only half of what I said, I
> said it encourages time constrained users to write middling (i.e. not
> great) documentation. Another person pointed out that structurally it
> really encourages terseness in the explanations of parameters, which I
> think is very true and have heard independently from others when talking
> about it as well. This is again not a requirement, but it is a real thing.
>
>
> >
> > I'll add that the major problem of documentation is not fancy
> > formatting but the content getting out of sync with the codebase.
> > Having documentation sitting next to the code is the preferred
> > antidote to doc rot, e.g. docstrings in lisp languages, Julia and
> > Python, the Linux kernel-doc system, doxygen, javadoc, ...
> >
>
> I mean, it is *an *antidote to doc rot. And sure, one that is used
> elsewhere. You could easily imagine one that didn't require it though.
> Perhaps doc files associated with objects (including closures) could embed
> a hash of the object they document, then you could see which things have
> changed since the documentation was updated and look at which documentation
> is still ok and which needs updating. That's just off the top of my head,
> I'm sure you could make the detection much more sophisticated.
>
> Or perhaps you could imagine two help systems, akin to --help and man for
> command line tools, one of which is minimalist showing usage, etc,
> generated by roxygen comments, and one of which is much more extensive, and
> not tied to (what could be extremely large) comments in the same .R file as
> the code.
>
>
This is basically what I meant by the template-based approach. Have the
details in the template, and the vitals in the doc comment block. Combine
the two and view the docs in different ways, dynamically.


> Best,
> ~G
>
>
> > It is true that R CMD check extensive checks help a lot as well in
> > this regard though only for things that can be checked automatically.
> >
> > Best,
> > Lionel
> >
> >
>
>
> --
> Gabriel Becker, PhD
> Scientist (Bioinformatics)
> Genentech Research
>
> [[alternative HTML version deleted]]
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 01/02/2018 12:20 PM, Gabriel Becker wrote:
[ lots deleted...]


Or perhaps you could imagine two help systems, akin to --help and man for
command line tools, one of which is minimalist showing usage, etc,
generated by roxygen comments, and one of which is much more extensive, and
not tied to (what could be extremely large) comments in the same .R file as
the code.


I think the input method and output form should be orthogonal.  Several 
front ends already implement minimalist help (e.g. RStudio displays the 
usage and description sections from the help page).


I'd rather have the help info coming from a separate file; other people 
apparently prefer to put it in the .R file.  I think both methods should 
be supported.  It makes sense to me to get both types of info from one 
place, but the author should be able to choose where that is.


Duncan Murdoch

P.S.  I've been playing around with Georgi Boshnakov's Rdpack package, 
putting together an RStudio plug-in to make usage updates trivial.  If 
anyone wants to try it out it's on my Github page for now 
(dmurdoch/Rdpack), but once it's usable, Georgi has said he will merge 
it back into his.


__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Joris Meys]

On Thu, Feb 1, 2018 at 6:20 PM, Gabriel Becker  wrote:

>
> Or perhaps you could imagine two help systems, akin to --help and man for
> command line tools, one of which is minimalist showing usage, etc,
> generated by roxygen comments, and one of which is much more extensive, and
> not tied to (what could be extremely large) comments in the same .R file as
> the code.
>

That sounds like basic help files and a few vignettes. I would argue we
have the tools to do this if necessary. One can even create topics in the
help file system (by using either Rd manually or through roxygen) that
aren't necessarily tied to a function. And each time I come to the same
conclusion: we have multiple tools to do this. We just need package
developers to care enough to do it.

-- 
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)


---
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

---
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Gabriel Becker]

On Thu, Feb 1, 2018 at 5:24 AM, Lionel Henry  wrote:

> On 31 janv. 2018, at 09:08, Gabriel Becker  wrote:
>
> > it *actively discourages* the bits it doesn't directly support.
>
> It may be discouraging to include Rd syntax in roxygen docs but only
> because the LaTeX-like syntax of Rd is burdensome, not because of
> roxygen. It is still handy to have inlined Rd as a backup and we do
> use it for the cases where we need finer grained control.
>

I only somewhat agree with this. Part of it is the Rd specifically, I
agree, but part of it is just the fact that it is a different syntax at
all. People who write roxygen documentation tend to think about and write
it in roxygen, I think. Any switch out to another syntax, thus introducing
two syntaxes side-by-side, is discouraged by the very fact that they are
thinking in roxygen comments.

Again, this is a "discouragement", not a disallowing. I know that people
who care deeply about writing absolutely top notch documentation, and who
also use roxygen will do the switch when called for, but the path of least
resistance, i.e. the pattern of behavior that is *encouraged* by roxygen2
is to not do that, and simply write documentation using only the supported
roxygen2 tags. I'm not saying this makes the system bad, per se. As I
pointed out, I use it in many of my packages (and it was my choice to do
so, not because I inherited code from someone who already did), but
pretending it doesn't encourage certain types of behavior doesn't seem like
the right way to go either.


>
> I agree with your sentiment that roxygen encourages writing of
> documentation for time-constrained users.
>

I do think it does that, but that was really only half of what I said, I
said it encourages time constrained users to write middling (i.e. not
great) documentation. Another person pointed out that structurally it
really encourages terseness in the explanations of parameters, which I
think is very true and have heard independently from others when talking
about it as well. This is again not a requirement, but it is a real thing.


>
> I'll add that the major problem of documentation is not fancy
> formatting but the content getting out of sync with the codebase.
> Having documentation sitting next to the code is the preferred
> antidote to doc rot, e.g. docstrings in lisp languages, Julia and
> Python, the Linux kernel-doc system, doxygen, javadoc, ...
>

I mean, it is *an *antidote to doc rot. And sure, one that is used
elsewhere. You could easily imagine one that didn't require it though.
Perhaps doc files associated with objects (including closures) could embed
a hash of the object they document, then you could see which things have
changed since the documentation was updated and look at which documentation
is still ok and which needs updating. That's just off the top of my head,
I'm sure you could make the detection much more sophisticated.

Or perhaps you could imagine two help systems, akin to --help and man for
command line tools, one of which is minimalist showing usage, etc,
generated by roxygen comments, and one of which is much more extensive, and
not tied to (what could be extremely large) comments in the same .R file as
the code.

Best,
~G


> It is true that R CMD check extensive checks help a lot as well in
> this regard though only for things that can be checked automatically.
>
> Best,
> Lionel
>
>


-- 
Gabriel Becker, PhD
Scientist (Bioinformatics)
Genentech Research

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Hadley Wickham]

On Thu, Feb 1, 2018 at 4:29 AM, Duncan Murdoch  wrote:
> On 31/01/2018 6:59 AM, Duncan Murdoch wrote:
>>
>> On 30/01/2018 11:39 PM, Hadley Wickham wrote:
>
>  [ lots deleted ]
>>>
>>> Personally, I don't find writing in comments any harder than writing
>>> in .Rd files, especially now that you can write in markdown and have
>>> it automatically translated to Rd formatting commands.
>>
>>
>> I didn't know about the possibility of Markdown.  That's a good thing.
>> You didn't say what editor you use, but RStudio is a good guess, and it
>> also makes it easier to write in comments.
>
>
> I've taken a look at the Markdown support, and I think that is fantastic.
> I'd rather it wasn't inline in the .R file (does it have to be?), but I'd
> say it tips the balance, and I'll certainly experiment with using that for
> new projects.

Please do let me know how it goes - often a fresh set of eyes reveals
problems that an experienced user is blind to.

> The only negative I see besides forcing inline docs is pretty minor:  I can
> see that supporting Rd markup within the Markdown text will on rare
> occasions cause lots of confusion (because users won't know why their
> backslashes are doing funny things).  I'd suggest that (at least optionally)
> you should escape anything that looks like Rd markup, so a user can put text
> like \item into the middle of a paragraph and not have the Rd parser see it.

Yes, that would certainly be nice. It's a little challenging because
we're using the commonmark parser, but it should be possible somehow.

Hadley

-- 
http://hadley.nz

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 01/02/2018 7:44 AM, Joris Meys wrote:



On Thu, Feb 1, 2018 at 1:29 PM, Duncan Murdoch > wrote:


On 31/01/2018 6:59 AM, Duncan Murdoch wrote:

On 30/01/2018 11:39 PM, Hadley Wickham wrote:

  [ lots deleted ]

Personally, I don't find writing in comments any harder than
writing
in .Rd files, especially now that you can write in markdown
and have
it automatically translated to Rd formatting commands.


I didn't know about the possibility of Markdown.  That's a good
thing.
You didn't say what editor you use, but RStudio is a good guess,
and it
also makes it easier to write in comments.


I've taken a look at the Markdown support, and I think that is
fantastic.  I'd rather it wasn't inline in the .R file (does it have
to be?), but I'd say it tips the balance, and I'll certainly
experiment with using that for new projects.


You don't have to put the Rmarkdown in the .R file of the function, 
there are ways to keep them in separate files. But keeping them in the 
same file does make it easier for Rmarkdown to eg generate the correct 
usage section and use the correct Rd makeup etc. At least that's my 
understanding of it. Hadley will hopefully correct me if I'm wrong.  I 
haven't checked all the options and possibilities yet in the latest 
iterations of the package.


I don't see that in the Roxygen2 docs, so hopefully it is possible, and 
someone will point out how it's done.


Duncan Murdoch

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 01/02/2018 8:17 AM, Georgi Boshnakov wrote:

It is indeed a matter of what the developer is comfortable with and the 
one-stop solution provided by devtools is difficult to beat.
This may also vary across projects. I use EMACS/ESS with and without roxygen2. 
In some cases EMACS/ESS+Org mode provides stunning benefits.

Updating "usage" statements in Rd files was mentioned several times.
Rdpack::reprompt() does this and more for functions, methods and classes.


Thanks for pointing that out (and for writing it)!  I had forgotten 
about your package.


Duncan Murdoch

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Lionel Henry]

On 31 janv. 2018, at 09:08, Gabriel Becker  wrote:

> it *actively discourages* the bits it doesn't directly support.

It may be discouraging to include Rd syntax in roxygen docs but only
because the LaTeX-like syntax of Rd is burdensome, not because of
roxygen. It is still handy to have inlined Rd as a backup and we do
use it for the cases where we need finer grained control.

I agree with your sentiment that roxygen encourages writing of
documentation for time-constrained users.

I'll add that the major problem of documentation is not fancy
formatting but the content getting out of sync with the codebase.
Having documentation sitting next to the code is the preferred
antidote to doc rot, e.g. docstrings in lisp languages, Julia and
Python, the Linux kernel-doc system, doxygen, javadoc, ...
It is true that R CMD check extensive checks help a lot as well in
this regard though only for things that can be checked automatically.

Best,
Lionel

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Georgi Boshnakov]

It is indeed a matter of what the developer is comfortable with and the 
one-stop solution provided by devtools is difficult to beat. 
This may also vary across projects. I use EMACS/ESS with and without roxygen2. 
In some cases EMACS/ESS+Org mode provides stunning benefits.

Updating "usage" statements in Rd files was mentioned several times. 
Rdpack::reprompt() does this and more for functions, methods and classes. 


Georgi Boshnakov

--
Date: Wed, 31 Jan 2018 07:53:18 -0800
From: Michael Lawrence <lawrence.mich...@gene.com>
To: Duncan Murdoch <murdoch.dun...@gmail.com>
Cc: "Brian G. Peterson" <br...@braverock.com>, "Suzen, Mehmet"
<mehmet.su...@gmail.com>, R-devel <r-devel@r-project.org>
Subject: Re: [Rd] Best practices in developing package: From a single
file
Message-ID:
<caoq5nyequdcsbczaqog6xqdeunx2hxg+4gghc0ews0nxgsz...@mail.gmail.com>
Content-Type: text/plain; charset="UTF-8"

I pretty much agree. I tried using roxygen when it was first released but
couldn't stand putting documentation in comments, especially for complex,
S4-based software. Rd is easy to read and write and lets me focus on the
task of writing documentation (focus is the hardest part of any task for
me). Probably the best feature of roxygen is that it automatically
generates \usage{}, which is otherwise completely redundant with the code.

I think the preceeding systems like doxygen, javadoc, gtk-doc, qtdoc, etc,
found a nice compromise through templating, where the bulk of the details
are written into the template, and just the essentials (usage, arguments,
return value) were embedded in the source file. I think this is even more
important for R, since we're often describing complex algorithms, while
most C/C++/Java software is oriented complex classes containing many
relatively simple methods.

Michael


On Tue, Jan 30, 2018 at 11:53 AM, Duncan Murdoch <murdoch.dun...@gmail.com>
wrote:

> On 30/01/2018 11:29 AM, Brian G. Peterson wrote:
>
>> On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
>>
>>> Dear R developers,
>>>
>>> I am wondering what are the best practices for developing an R
>>> package. I am aware of Hadley Wickham's best practice
>>> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
>>> years ago there were some tools for generating a package out of a
>>> single file, such as using package.skeleton, but no auto-generated
>>> documentation. Do you know a way to generate documentation and a
>>> package out of single R source file, or from an environment?
>>>
>>
>> Mehmet,
>>
>> This list is for development of the R language itself and closely
>> related tools.  There is a separate list, R-pkg-devel, for development
>> of packages.
>>
>> Since you're here, I'll try to answer your question.
>>
>> package.skeleton can create a package from all the R functions in a
>> specified environment.  So if you load all the functions that you want
>> in your new package into your R environment, then call
>> package.skeleton, you'll have a starting point.
>>
>> At that point, I would probably recommend moving to RStudio, and using
>> RStudio to generate markdown comments for roxygen for all your newly
>> created function files.  Then you could finish off the documentation by
>> writing it in these roxygen skeletons or copying and pasting from
>> comments in your original code files.
>>
>
> I'd agree about moving to RStudio, but I think Roxygen is the wrong
> approach for documentation.  package.skeleton() will have done the boring
> mechanical part of setting up your .Rd files; all you have to do is edit
> some content into them.  (Use prompt() to add a new file if you add a new
> function later, don't run package.skeleton() again.)
>
> This isn't the fashionable point of view, but I think it is easier to get
> good documentation that way than using Roxygen.  (It's easier to get bad
> documentation using Roxygen, but who wants that?)
>
> The reason I think this is that good documentation requires work and
> thought.  You need to think about the markup that will get your point
> across, you need to think about putting together good examples, etc.
> This is *harder* in Roxygen than if you are writing Rd files, because
> Roxygen is a thin front end to produce Rd files from comments in your .R
> files.  To get good stuff in the help page, you need just as much work as
> in writing the .Rd file directly, but then you need to add another layer on
> top to put in in a comment.  Most people don't bother.
>
> I don't know any packages with what I'd consider to be good documentation
> that use 

Re: [Rd] Best practices in developing package: From a single file

[Joris Meys]

On Thu, Feb 1, 2018 at 1:29 PM, Duncan Murdoch 
wrote:

> On 31/01/2018 6:59 AM, Duncan Murdoch wrote:
>
>> On 30/01/2018 11:39 PM, Hadley Wickham wrote:
>>
>  [ lots deleted ]
>
>> Personally, I don't find writing in comments any harder than writing
>>> in .Rd files, especially now that you can write in markdown and have
>>> it automatically translated to Rd formatting commands.
>>>
>>
>> I didn't know about the possibility of Markdown.  That's a good thing.
>> You didn't say what editor you use, but RStudio is a good guess, and it
>> also makes it easier to write in comments.
>>
>
> I've taken a look at the Markdown support, and I think that is fantastic.
> I'd rather it wasn't inline in the .R file (does it have to be?), but I'd
> say it tips the balance, and I'll certainly experiment with using that for
> new projects.
>

You don't have to put the Rmarkdown in the .R file of the function, there
are ways to keep them in separate files. But keeping them in the same file
does make it easier for Rmarkdown to eg generate the correct usage section
and use the correct Rd makeup etc. At least that's my understanding of it.
Hadley will hopefully correct me if I'm wrong.  I haven't checked all the
options and possibilities yet in the latest iterations of the package.

Cheers
Joris

-- 
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)


---
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

---
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 31/01/2018 6:59 AM, Duncan Murdoch wrote:

On 30/01/2018 11:39 PM, Hadley Wickham wrote:

 [ lots deleted ]

Personally, I don't find writing in comments any harder than writing
in .Rd files, especially now that you can write in markdown and have
it automatically translated to Rd formatting commands.


I didn't know about the possibility of Markdown.  That's a good thing.
You didn't say what editor you use, but RStudio is a good guess, and it
also makes it easier to write in comments.


I've taken a look at the Markdown support, and I think that is 
fantastic.  I'd rather it wasn't inline in the .R file (does it have to 
be?), but I'd say it tips the balance, and I'll certainly experiment 
with using that for new projects.


The only negative I see besides forcing inline docs is pretty minor:  I 
can see that supporting Rd markup within the Markdown text will on rare 
occasions cause lots of confusion (because users won't know why their 
backslashes are doing funny things).  I'd suggest that (at least 
optionally) you should escape anything that looks like Rd markup, so a 
user can put text like \item into the middle of a paragraph and not have 
the Rd parser see it.


Duncan Murdoch

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 31/01/2018 8:59 AM, Mark van der Loo wrote:

I fully agree with Joris and Hadley on roxygen2.


Additionally:

I wrote and published my first package before roxygen (or roxygen2) was 
available. I found editing .Rd extremely terse (especially when code is 
updated). For example, the fact that there are no spaces allowed between 
} and { in \param{}{} has hurt my brain quite a few times, especially 


There's no \param macro in Rd.  You're probably thinking of \item{}{} or 
\section{}{}, or some other two-arg macro.  There aren't very many of 
them, but there are a few.


If it really is \item, then the error message you get would look 
something like this:


Warning: bad markup (extra space?) at foo.Rd:15:16

That's column 16 of line 15.  I'm not sure this guess is right, because 
that message does seem pretty informative.


There are also a couple of 1 or 2 argument macros (\eqn and \deqn), 
where the space would make the parser think you were using the 1 
argument version.  I think that's the same behaviour as LaTeX, which the 
Rd format is loosely based on.



since R CMD check did not give any useful error messages about it. For 
me it is a signal that the Rd parser is rather primitive.


Originally the format was defined in a really ad hoc way:  help pages 
were formed not by parsing the Rd file, but by applying a sequence of 
substitutions to it.  I wrote a parser following the usual R policy of 
trying not to break too much existing code.  This wasn't easy because 
the format had grown into something fairly awful, but I wouldn't call it 
primitive.  At the time I was really hoping someone else would propose 
something better, but I don't think that ever happened.


Duncan Murdoch


 On the other
hand Roxygen2 now usually gives pretty good error messages when I syntax 
error something.


Also, the 'parent' of roxygen is Doxygen, which was already widely used 
(also by me) in the C/C++ community before roxygen was published. I 
cannot remember anyone ever complaining about C/C++ documentation 
deteriorating because of Doxygen.



-Mark


Op wo 31 jan. 2018 om 14:02 schreef Joris Meys >:


On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch
>
wrote:

 > On 31/01/2018 6:33 AM, Joris Meys wrote:
 >
 > 3. given your criticism, I'd like your opinion on where I can
improve the
 >> documentation of
https://github.com/CenterForStatistics-UGent/pim. I'm
 >> currently busy updating the help files for a next release on
CRAN, so your
 >> input is more than welcome.
 >>
 >
 > After this invitation I sent some private comments to Joris.  I
would say
 > his package does a pretty good job of documentation; it isn't the
kind of
 > Roxygen-using package that I was complaining about.  So I will
say I have
 > received an example of a Roxygen-using package that
 > has good help pages.
 >

Thank you for the nice compliment and the valuable tips.

--
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)



---
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

---
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

         [[alternative HTML version deleted]]

__
R-devel@r-project.org  mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel



__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Gabriel Becker]

Joris,

With the large caveat that I am not Duncan, and thus am not speaking for
him, I can see an argument for his claim that I think is, more or less,
true.

roxygen2 (as far as I know as someone who uses it at least some of the
time) maps to only a subset of Rd. It is the most commonly used subset, and
so you can do most common things with it, but I think a pretty good case
can be made for the fact that it *actively discourages* the bits it doesn't
directly support. Ie doing things that would require you to put Rd syntax
into the roxygen comments. In as much as those aspects of Rd are required
for good documentation *in some cases*, in those cases, good documentation
is discouraged. Not disallowed, mind you - you CAN put the Rd syntax into
your roxygen comments and have it work - but discouraged.

There is also the case that I think Michael was alluding to, that in some
types of R software things that belong in the same help file are not
co-localized in R code. This is , again, supported by oxygen, of course,
but it removes one of the primary benefits of the system, i.e.
documentation-proximity-to-code.

Also, as I understood Duncan's comments, he was not saying good
documentation CANNOT be written in oxygen, just like good R code CAN be
written in notepad, rather than an IDE like RStudio or Emacs+ESS, but doing
so doesn't encourage the process.

All that said, at the end of the day, I generally agree with what Yehui
said as well. If you use roxygen2 and feel that it helps you to write good
documentation, great! Use it.  Thats ultimately not a statement about what
kind of documentation it encourages.

As a final thought, my personal view is that roxygen2 does not encourage
good or bad documentation, but rather middling documentation. It encourages
new users and those with major time or focus constraints to document things
more than they would without it, which is good, but doesn't encourage
really top notch documentation either and as with all things, hand-crafted
"artisanal" documentation will often be of higher quality.

Best,
~G

On Wed, Jan 31, 2018 at 8:35 AM, Suzen, Mehmet <su...@acm.org> wrote:

> Dear Dr. Pfaff,
>
> Thank you for this, creating a package out of single file was my
> oriingal question, but not only creating and also maintaining it that
> way so R package is an artifact of the development process rather than
> "manually maintained" structure. I will have look at your sources.
>
> Best,
>
> Mehmet Süzen
> <su...@acm.org>
>
>
> On 31 January 2018 at 15:51, Pfaff, Bernhard Dr.
> <bernhard_pf...@fra.invesco.com> wrote:
> > Dear All:
> >
> > stepping in late, but @Joris, if you would like to take 'from a single
> file' literally,
> > have a look at:
> >
> > https://github.com/bpfaff/lp4rp
> >
> > (lp4rp: literate programming for R packages);
> >
> > Cheers,
> > Bernhard
> >
> > ps:  incidentally, within the noweb-file roxygen is employed.
> >
> > -Ursprüngliche Nachricht-
> > Von: R-devel [mailto:r-devel-boun...@r-project.org] Im Auftrag von
> Joris Meys
> > Gesendet: Mittwoch, 31. Januar 2018 14:02
> > An: Duncan Murdoch
> > Cc: r-devel
> > Betreff: [EXT] Re: [Rd] Best practices in developing package: From a
> single file
> >
> > On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <
> murdoch.dun...@gmail.com>
> > wrote:
> >
> >> On 31/01/2018 6:33 AM, Joris Meys wrote:
> >>
> >> 3. given your criticism, I'd like your opinion on where I can improve
> >> the
> >>> documentation of https://github.com/CenterForStatistics-UGent/pim.
> >>> I'm currently busy updating the help files for a next release on
> >>> CRAN, so your input is more than welcome.
> >>>
> >>
> >> After this invitation I sent some private comments to Joris.  I would
> >> say his package does a pretty good job of documentation; it isn't the
> >> kind of Roxygen-using package that I was complaining about.  So I will
> >> say I have received an example of a Roxygen-using package that has
> >> good help pages.
> >>
> >
> > Thank you for the nice compliment and the valuable tips.
> >
> > --
> > Joris Meys
> > Statistical consultant
> >
> > Department of Data Analysis and Mathematical Modelling Ghent University
> Coupure Links 653, B-9000 Gent (Belgium) <https://maps.google.com/?q=
> Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium=gmail=g>
> >
> > ---
> > Biowiskundedagen 2017-2018
> > http://www.biowiskundedagen.ugent.be/
> >
> > ---
> > Disclaimer : http://helpdesk.ugent.be/e-maildisclaime

Re: [Rd] Best practices in developing package: From a single file

[Suzen, Mehmet]

Dear Dr. Pfaff,

Thank you for this, creating a package out of single file was my
oriingal question, but not only creating and also maintaining it that
way so R package is an artifact of the development process rather than
"manually maintained" structure. I will have look at your sources.

Best,

Mehmet Süzen
<su...@acm.org>


On 31 January 2018 at 15:51, Pfaff, Bernhard Dr.
<bernhard_pf...@fra.invesco.com> wrote:
> Dear All:
>
> stepping in late, but @Joris, if you would like to take 'from a single file' 
> literally,
> have a look at:
>
> https://github.com/bpfaff/lp4rp
>
> (lp4rp: literate programming for R packages);
>
> Cheers,
> Bernhard
>
> ps:  incidentally, within the noweb-file roxygen is employed.
>
> -Ursprüngliche Nachricht-
> Von: R-devel [mailto:r-devel-boun...@r-project.org] Im Auftrag von Joris Meys
> Gesendet: Mittwoch, 31. Januar 2018 14:02
> An: Duncan Murdoch
> Cc: r-devel
> Betreff: [EXT] Re: [Rd] Best practices in developing package: From a single 
> file
>
> On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <murdoch.dun...@gmail.com>
> wrote:
>
>> On 31/01/2018 6:33 AM, Joris Meys wrote:
>>
>> 3. given your criticism, I'd like your opinion on where I can improve
>> the
>>> documentation of https://github.com/CenterForStatistics-UGent/pim.
>>> I'm currently busy updating the help files for a next release on
>>> CRAN, so your input is more than welcome.
>>>
>>
>> After this invitation I sent some private comments to Joris.  I would
>> say his package does a pretty good job of documentation; it isn't the
>> kind of Roxygen-using package that I was complaining about.  So I will
>> say I have received an example of a Roxygen-using package that has
>> good help pages.
>>
>
> Thank you for the nice compliment and the valuable tips.
>
> --
> Joris Meys
> Statistical consultant
>
> Department of Data Analysis and Mathematical Modelling Ghent University 
> Coupure Links 653, B-9000 Gent (Belgium) 
> <https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium=gmail=g>
>
> ---
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> ---
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
>
> [[alternative HTML version deleted]]
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> *
> Confidentiality Note: The information contained in this ...{{dropped:10}}
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Michael Lawrence]

I pretty much agree. I tried using roxygen when it was first released but
couldn't stand putting documentation in comments, especially for complex,
S4-based software. Rd is easy to read and write and lets me focus on the
task of writing documentation (focus is the hardest part of any task for
me). Probably the best feature of roxygen is that it automatically
generates \usage{}, which is otherwise completely redundant with the code.

I think the preceeding systems like doxygen, javadoc, gtk-doc, qtdoc, etc,
found a nice compromise through templating, where the bulk of the details
are written into the template, and just the essentials (usage, arguments,
return value) were embedded in the source file. I think this is even more
important for R, since we're often describing complex algorithms, while
most C/C++/Java software is oriented complex classes containing many
relatively simple methods.

Michael


On Tue, Jan 30, 2018 at 11:53 AM, Duncan Murdoch 
wrote:

> On 30/01/2018 11:29 AM, Brian G. Peterson wrote:
>
>> On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
>>
>>> Dear R developers,
>>>
>>> I am wondering what are the best practices for developing an R
>>> package. I am aware of Hadley Wickham's best practice
>>> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
>>> years ago there were some tools for generating a package out of a
>>> single file, such as using package.skeleton, but no auto-generated
>>> documentation. Do you know a way to generate documentation and a
>>> package out of single R source file, or from an environment?
>>>
>>
>> Mehmet,
>>
>> This list is for development of the R language itself and closely
>> related tools.  There is a separate list, R-pkg-devel, for development
>> of packages.
>>
>> Since you're here, I'll try to answer your question.
>>
>> package.skeleton can create a package from all the R functions in a
>> specified environment.  So if you load all the functions that you want
>> in your new package into your R environment, then call
>> package.skeleton, you'll have a starting point.
>>
>> At that point, I would probably recommend moving to RStudio, and using
>> RStudio to generate markdown comments for roxygen for all your newly
>> created function files.  Then you could finish off the documentation by
>> writing it in these roxygen skeletons or copying and pasting from
>> comments in your original code files.
>>
>
> I'd agree about moving to RStudio, but I think Roxygen is the wrong
> approach for documentation.  package.skeleton() will have done the boring
> mechanical part of setting up your .Rd files; all you have to do is edit
> some content into them.  (Use prompt() to add a new file if you add a new
> function later, don't run package.skeleton() again.)
>
> This isn't the fashionable point of view, but I think it is easier to get
> good documentation that way than using Roxygen.  (It's easier to get bad
> documentation using Roxygen, but who wants that?)
>
> The reason I think this is that good documentation requires work and
> thought.  You need to think about the markup that will get your point
> across, you need to think about putting together good examples, etc.
> This is *harder* in Roxygen than if you are writing Rd files, because
> Roxygen is a thin front end to produce Rd files from comments in your .R
> files.  To get good stuff in the help page, you need just as much work as
> in writing the .Rd file directly, but then you need to add another layer on
> top to put in in a comment.  Most people don't bother.
>
> I don't know any packages with what I'd consider to be good documentation
> that use Roxygen.  It's just too easy to write minimal documentation that
> passes checks, so Roxygen users don't keep refining it.
>
> (There are plenty of examples of packages that write bad documentation
> directly to .Rd as well.  I just don't know of examples of packages with
> good documentation that use Roxygen.)
>
> Based on my criticism last week of git and Github, I expect to be called a
> grumpy old man for holding this point of view.  I'd actually like to be
> proven wrong.  So to anyone who disagrees with me:  rather than just
> calling me names, how about some examples of Roxygen-using packages that
> have good help pages with good explanations, and good examples in them?
>
> Back to Mehmet's question:  I think Hadley's book is pretty good, and I'd
> recommend most of it, just not the Roxygen part.
>
> Duncan Murdoch
>
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Yihui Xie]

Similarly, I created this example a couple of years ago:
https://github.com/yihui/rlp which shows that you can create a package
from R Markdown documents (or any documents that knitr supports).
Basically you can start with an R Markdown document, and after
clicking a button in RStudio, you will get a full R package, with R
code, vignettes, and Rd (killing three birds with one stone). The
reason that you can get Rd is because of roxygen2.

I'm not interested in convincing Duncan of using roxygen (or
GIT/Github). It is fine that one loves or hates a tool. Just use tools
that make yourself comfortable. To me as a package developer, roxygen2
is indispensable (so are GIT/Github), and I use it in all my packages.
I had almost lost interest in developing R packages about 8 years ago
just because I found writing raw Rd extremely frustrating. Then
fortunately, roxygen was born, just in time.

Personally, it doesn't bother me if Duncan thinks roxygen-based
package documentations are typically of poor quality. I care a lot of
about documentation, and sometimes spend months after months on
documentation (Rd, vignettes, websites, and books). I'd very much like
to volunteer to have Duncan use any of my packages as examples of
"poor-quality roxygen-based documentation", and let's figure out why
they are poor (i.e., do we blame it on roxygen2 or myself?).

Regards,
Yihui
--
https://yihui.name


On Wed, Jan 31, 2018 at 8:51 AM, Pfaff, Bernhard Dr.
<bernhard_pf...@fra.invesco.com> wrote:
> Dear All:
>
> stepping in late, but @Joris, if you would like to take 'from a single file' 
> literally,
> have a look at:
>
> https://github.com/bpfaff/lp4rp
>
> (lp4rp: literate programming for R packages);
>
> Cheers,
> Bernhard
>
> ps:  incidentally, within the noweb-file roxygen is employed.
>
> -Ursprüngliche Nachricht-
> Von: R-devel [mailto:r-devel-boun...@r-project.org] Im Auftrag von Joris Meys
> Gesendet: Mittwoch, 31. Januar 2018 14:02
> An: Duncan Murdoch
> Cc: r-devel
> Betreff: [EXT] Re: [Rd] Best practices in developing package: From a single 
> file
>
> On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <murdoch.dun...@gmail.com>
> wrote:
>
>> On 31/01/2018 6:33 AM, Joris Meys wrote:
>>
>> 3. given your criticism, I'd like your opinion on where I can improve
>> the
>>> documentation of https://github.com/CenterForStatistics-UGent/pim.
>>> I'm currently busy updating the help files for a next release on
>>> CRAN, so your input is more than welcome.
>>>
>>
>> After this invitation I sent some private comments to Joris.  I would
>> say his package does a pretty good job of documentation; it isn't the
>> kind of Roxygen-using package that I was complaining about.  So I will
>> say I have received an example of a Roxygen-using package that has
>> good help pages.
>>
>
> Thank you for the nice compliment and the valuable tips.
>
> --
> Joris Meys
> Statistical consultant
>
> Department of Data Analysis and Mathematical Modelling Ghent University 
> Coupure Links 653, B-9000 Gent (Belgium) 
> <https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium=gmail=g>
>
> ---
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> ---
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
>
> [[alternative HTML version deleted]]
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> *
> Confidentiality Note: The information contained in this ...{{dropped:10}}
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Pfaff, Bernhard Dr.]

Dear All:

stepping in late, but @Joris, if you would like to take 'from a single file' 
literally,
have a look at:

https://github.com/bpfaff/lp4rp

(lp4rp: literate programming for R packages); 

Cheers,
Bernhard

ps:  incidentally, within the noweb-file roxygen is employed.

-Ursprüngliche Nachricht-
Von: R-devel [mailto:r-devel-boun...@r-project.org] Im Auftrag von Joris Meys
Gesendet: Mittwoch, 31. Januar 2018 14:02
An: Duncan Murdoch
Cc: r-devel
Betreff: [EXT] Re: [Rd] Best practices in developing package: From a single file

On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <murdoch.dun...@gmail.com>
wrote:

> On 31/01/2018 6:33 AM, Joris Meys wrote:
>
> 3. given your criticism, I'd like your opinion on where I can improve 
> the
>> documentation of https://github.com/CenterForStatistics-UGent/pim. 
>> I'm currently busy updating the help files for a next release on 
>> CRAN, so your input is more than welcome.
>>
>
> After this invitation I sent some private comments to Joris.  I would 
> say his package does a pretty good job of documentation; it isn't the 
> kind of Roxygen-using package that I was complaining about.  So I will 
> say I have received an example of a Roxygen-using package that has 
> good help pages.
>

Thank you for the nice compliment and the valuable tips.

--
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling Ghent University Coupure 
Links 653, B-9000 Gent (Belgium) 
<https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium=gmail=g>

---
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

---
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
*
Confidentiality Note: The information contained in this ...{{dropped:10}}

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Mark van der Loo]

I fully agree with Joris and Hadley on roxygen2.


Additionally:

I wrote and published my first package before roxygen (or roxygen2) was
available. I found editing .Rd extremely terse (especially when code is
updated). For example, the fact that there are no spaces allowed between }
and { in \param{}{} has hurt my brain quite a few times, especially since R
CMD check did not give any useful error messages about it. For me it is a
signal that the Rd parser is rather primitive. On the other hand Roxygen2
now usually gives pretty good error messages when I syntax error something.

Also, the 'parent' of roxygen is Doxygen, which was already widely used
(also by me) in the C/C++ community before roxygen was published. I cannot
remember anyone ever complaining about C/C++ documentation deteriorating
because of Doxygen.


-Mark


Op wo 31 jan. 2018 om 14:02 schreef Joris Meys :

> On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch 
> wrote:
>
> > On 31/01/2018 6:33 AM, Joris Meys wrote:
> >
> > 3. given your criticism, I'd like your opinion on where I can improve the
> >> documentation of https://github.com/CenterForStatistics-UGent/pim. I'm
> >> currently busy updating the help files for a next release on CRAN, so
> your
> >> input is more than welcome.
> >>
> >
> > After this invitation I sent some private comments to Joris.  I would say
> > his package does a pretty good job of documentation; it isn't the kind of
> > Roxygen-using package that I was complaining about.  So I will say I have
> > received an example of a Roxygen-using package that
> > has good help pages.
> >
>
> Thank you for the nice compliment and the valuable tips.
>
> --
> Joris Meys
> Statistical consultant
>
> Department of Data Analysis and Mathematical Modelling
> Ghent University
> Coupure Links 653, B-9000 Gent (Belgium)
> <
> https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium=gmail=g
> >
>
> ---
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> ---
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
>
> [[alternative HTML version deleted]]
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Joris Meys]

On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch 
wrote:

> On 31/01/2018 6:33 AM, Joris Meys wrote:
>
> 3. given your criticism, I'd like your opinion on where I can improve the
>> documentation of https://github.com/CenterForStatistics-UGent/pim. I'm
>> currently busy updating the help files for a next release on CRAN, so your
>> input is more than welcome.
>>
>
> After this invitation I sent some private comments to Joris.  I would say
> his package does a pretty good job of documentation; it isn't the kind of
> Roxygen-using package that I was complaining about.  So I will say I have
> received an example of a Roxygen-using package that
> has good help pages.
>

Thank you for the nice compliment and the valuable tips.

-- 
Joris Meys
Statistical consultant

Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)


---
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/

---
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Dirk Eddelbuettel]

(Please do not quote without attribution)

On 30 January 2018 at 20:44, Hadley Wickham wrote:
| Personally, I think the biggest problem with package.skeleton() is
| that it assumes that the source of truth is objects in an environment.
| This seems the wrong way around to me.

Basically irrelevant as it is optional behaviour.  With various packages at
work I may by now have created several dozen packages via package.skeleton(),
and I essentially never submitted an existing function.

Dirk

-- 
http://dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 31/01/2018 6:33 AM, Joris Meys wrote:

3. given your criticism, I'd like your opinion on where I can improve 
the documentation of https://github.com/CenterForStatistics-UGent/pim. 
I'm currently busy updating the help files for a next release on CRAN, 
so your input is more than welcome.


After this invitation I sent some private comments to Joris.  I would 
say his package does a pretty good job of documentation; it isn't the 
kind of Roxygen-using package that I was complaining about.  So I will 
say I have received an example of a Roxygen-using package that

has good help pages.

Duncan Murdoch

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 31/01/2018 6:33 AM, Joris Meys wrote:

Dear Duncan,

With all respect, but I strongly disagree on your stance regarding 
roxygen2 for multiple reasons:


1. It is in my humble opinion not correct to evaluate a tool based on 
the abuse of some users. It's not because people write packages with bad 
documentation, that roxygen2 is to blame. I use roxygen2, and I care a 
great deal about documentation. So I actually took a bit offense there.


Sorry about that.  I did say I wanted to be proven wrong.

2. Writing .Rd files directly means that you have to write out the usage 
yourself, know the different tags needed for documenting different types 
of generics and methods, and so forth. 


Not at all --- that's what the prompt() function does.

It means a lot more iterations to 
get every tag right so that R CMD check does not complain any more. It 
requires a more detailed knowledge of the entire Rd tag system compared 
to letting roxygen2 do the standard work for you. So one could argue 
that the extra knowledge required would actually hinder starting 
developers to write good documentation as opposed to help them.


New users (and old users) should use prompt() to set up the basic help page.

There are situations where prompt() doesn't help, namely edits to 
existing pages:


 - adding a second function.
 - adding new parameters.

I think the infrastructure is there to allow functions to be written to
do these things, but as far as I know nobody has done it.



3. given your criticism, I'd like your opinion on where I can improve 
the documentation of https://github.com/CenterForStatistics-UGent/pim. 
I'm currently busy updating the help files for a next release on CRAN, 
so your input is more than welcome.


Sure, I'll take a look.

I'm not going to force anyone to use roxygen2. But I personally find it 
easier to have the function right below the documentation, so that any 
change to the function can immediately be documented as well. You prefer 
to do this by keeping that strictly separated, which is absolutely fine. 
It's just not my prefered workflow. Different animal, different habits I 
guess.


On a sidenote: I had a lot of complaints about earlier iterations of 
roxygen2 and the many changes to tags and their meanings, but the 
roxygen2 package matured in the meantime and has been a stable and 
reliable tool for me the past years.


I formed my opinion several years ago, so perhaps I should take another 
look.  One problem is lock-in:  once you write an Rd file, you can't (as 
far as I know) easily import it as Roxygen markup.  So I'd have to start 
a new package to get experience with Roxygen.  Maybe it should be the 
package that adds the Rd tools mentioned above :-).


Duncan Murdoch



Kind regards
Joris



On Tue, Jan 30, 2018 at 8:53 PM, Duncan Murdoch 
> wrote:


On 30/01/2018 11:29 AM, Brian G. Peterson wrote:

On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:

Dear R developers,

I am wondering what are the best practices for developing an R
package. I am aware of Hadley Wickham's best practice
documentation/book (http://r-pkgs.had.co.nz/).  I recall a
couple of
years ago there were some tools for generating a package out
of a
single file, such as using package.skeleton, but no
auto-generated
documentation. Do you know a way to generate documentation and a
package out of single R source file, or from an environment?


Mehmet,

This list is for development of the R language itself and closely
related tools.  There is a separate list, R-pkg-devel, for
development
of packages.

Since you're here, I'll try to answer your question.

package.skeleton can create a package from all the R functions in a
specified environment.  So if you load all the functions that
you want
in your new package into your R environment, then call
package.skeleton, you'll have a starting point.

At that point, I would probably recommend moving to RStudio, and
using
RStudio to generate markdown comments for roxygen for all your newly
created function files.  Then you could finish off the
documentation by
writing it in these roxygen skeletons or copying and pasting from
comments in your original code files.


I'd agree about moving to RStudio, but I think Roxygen is the wrong
approach for documentation.  package.skeleton() will have done the
boring mechanical part of setting up your .Rd files; all you have to
do is edit some content into them.  (Use prompt() to add a new file
if you add a new function later, don't run package.skeleton() again.)

This isn't the fashionable point of view, but I think it is easier
to get good documentation that 

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 30/01/2018 11:39 PM, Hadley Wickham wrote:

On Tue, Jan 30, 2018 at 4:55 PM, Duncan Murdoch
 wrote:

On 30/01/2018 4:30 PM, Kenny Bell wrote:


In response to Duncan regarding the use of roxygen2 from the point of view
of a current user, I believe the issue he brings up is one of correlation
rather than causation.



Could be.  However, I think editing comments in a .R file is a bit harder
than editing text in a .Rd file, so I think the format discourages editing.
I think it does make it easier to pass R CMD check the first time, but I
don't think you should be satisfied with that.


One counter-point: I find it much easier to remember to update the
documentation when you update the code, if the code and the
documentation are very close together. I think mingling code and
documentation in the same file does add a subtle pressure to write
shorter docs, but I'm not entirely sure that's a bad thing - for long
form writing, vignettes are a much better solution anyway (since you
often want to mingle code and explanation).


I agree about your first point to some extent, but it works best when 
the documentation is short.  Once you get a long help page, you still 
have the long distance.  Some functions need long help pages because 
they do a lot.


RStudio provides pretty good support for both forms of documentation. 
If I've just modified a function, I can type the name of the function in 
the "Go to file/function" box at the top, and go directly to the right 
.Rd file.  That reduces the "distance".  I imagine ESS and other editors 
have (or could have) something similar.


Regarding vignettes versus help pages:  I think they have different 
purposes.  You want the technical documentation in the help page to be 
really complete, to explain what each parameter does, what the value is, 
with simple examples.  I won't try to embarrass anyone with specific 
examples (unless someone volunteers ;-), but I would say the general 
trend in Roxygen-using packages is to be quite incomplete, with one-line 
parameter descriptions being all you get.  Sometimes this is sufficient, 
but often it isn't.  The goal appears to be to pass checks, not to write 
good documentation.  Some wild speculation:  maybe the proximity to the 
source makes authors think the source is visible to the user looking for 
help.


Vignettes get to leave out rarely used parameters, but get to show how 
things are used in longer examples, combining multiple functions.  I've 
tried to write the rgl documentation this way, with links from the 
vignette to the help pages.


I haven't added links from the help page to the location in the vignette 
where the function is put in context, but that's probably possible 
(provided HTML help is used, and the vignette is in HTML).



Personally, I don't find writing in comments any harder than writing
in .Rd files, especially now that you can write in markdown and have
it automatically translated to Rd formatting commands.  


I didn't know about the possibility of Markdown.  That's a good thing. 
You didn't say what editor you use, but RStudio is a good guess, and it 
also makes it easier to write in comments.


And on the

negative side of Rd, I find it frustrating to have to copy and paste
the function definition to the usage section every time I modify an
argument. It just feels like unnecessary busywork that the computer
should be able to do for me (although I do understand why it is not
possible).


The computer (via R CMD check) does tell you what is missing.  I'd guess 
that the transfer could be done automatically, but it would be in a very 
editor-specific way, e.g. an RStudio add-in, or Emacs macro, or 
whatever.  Someone should write it :-).





Writing my first piece of R documentation was made much easier by using
roxygen2, and it shallowed the learning curve substantially.


I'm not completely up to date on Roxygen2 these days:  can you do some pages
in Rd, others in Roxygen?  That's not quite as good as being able to switch
back and forth, but it would allow you to start in Roxygen, then gradually
move to Rd when editing there was easier.


Yes, that's possible, and to protect you in mixed environment,
roxygen2 will never overwrite a file that it did not itself create.


Good!  Perhaps I should give it another look.

Duncan

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Joris Meys]

Dear Duncan,

With all respect, but I strongly disagree on your stance regarding roxygen2
for multiple reasons:

1. It is in my humble opinion not correct to evaluate a tool based on the
abuse of some users. It's not because people write packages with bad
documentation, that roxygen2 is to blame. I use roxygen2, and I care a
great deal about documentation. So I actually took a bit offense there.

2. Writing .Rd files directly means that you have to write out the usage
yourself, know the different tags needed for documenting different types of
generics and methods, and so forth. It means a lot more iterations to get
every tag right so that R CMD check does not complain any more. It requires
a more detailed knowledge of the entire Rd tag system compared to letting
roxygen2 do the standard work for you. So one could argue that the extra
knowledge required would actually hinder starting developers to write good
documentation as opposed to help them.

3. given your criticism, I'd like your opinion on where I can improve the
documentation of https://github.com/CenterForStatistics-UGent/pim. I'm
currently busy updating the help files for a next release on CRAN, so your
input is more than welcome.

I'm not going to force anyone to use roxygen2. But I personally find it
easier to have the function right below the documentation, so that any
change to the function can immediately be documented as well. You prefer to
do this by keeping that strictly separated, which is absolutely fine. It's
just not my prefered workflow. Different animal, different habits I guess.

On a sidenote: I had a lot of complaints about earlier iterations of
roxygen2 and the many changes to tags and their meanings, but the roxygen2
package matured in the meantime and has been a stable and reliable tool for
me the past years.

Kind regards
Joris



On Tue, Jan 30, 2018 at 8:53 PM, Duncan Murdoch 
wrote:

> On 30/01/2018 11:29 AM, Brian G. Peterson wrote:
>
>> On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
>>
>>> Dear R developers,
>>>
>>> I am wondering what are the best practices for developing an R
>>> package. I am aware of Hadley Wickham's best practice
>>> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
>>> years ago there were some tools for generating a package out of a
>>> single file, such as using package.skeleton, but no auto-generated
>>> documentation. Do you know a way to generate documentation and a
>>> package out of single R source file, or from an environment?
>>>
>>
>> Mehmet,
>>
>> This list is for development of the R language itself and closely
>> related tools.  There is a separate list, R-pkg-devel, for development
>> of packages.
>>
>> Since you're here, I'll try to answer your question.
>>
>> package.skeleton can create a package from all the R functions in a
>> specified environment.  So if you load all the functions that you want
>> in your new package into your R environment, then call
>> package.skeleton, you'll have a starting point.
>>
>> At that point, I would probably recommend moving to RStudio, and using
>> RStudio to generate markdown comments for roxygen for all your newly
>> created function files.  Then you could finish off the documentation by
>> writing it in these roxygen skeletons or copying and pasting from
>> comments in your original code files.
>>
>
> I'd agree about moving to RStudio, but I think Roxygen is the wrong
> approach for documentation.  package.skeleton() will have done the boring
> mechanical part of setting up your .Rd files; all you have to do is edit
> some content into them.  (Use prompt() to add a new file if you add a new
> function later, don't run package.skeleton() again.)
>
> This isn't the fashionable point of view, but I think it is easier to get
> good documentation that way than using Roxygen.  (It's easier to get bad
> documentation using Roxygen, but who wants that?)
>
> The reason I think this is that good documentation requires work and
> thought.  You need to think about the markup that will get your point
> across, you need to think about putting together good examples, etc.
> This is *harder* in Roxygen than if you are writing Rd files, because
> Roxygen is a thin front end to produce Rd files from comments in your .R
> files.  To get good stuff in the help page, you need just as much work as
> in writing the .Rd file directly, but then you need to add another layer on
> top to put in in a comment.  Most people don't bother.
>
> I don't know any packages with what I'd consider to be good documentation
> that use Roxygen.  It's just too easy to write minimal documentation that
> passes checks, so Roxygen users don't keep refining it.
>
> (There are plenty of examples of packages that write bad documentation
> directly to .Rd as well.  I just don't know of examples of packages with
> good documentation that use Roxygen.)
>
> Based on my criticism last week of git and Github, I expect to be called a
> grumpy 

Re: [Rd] Best practices in developing package: From a single file

[Hadley Wickham]

>> There is package.skeleton() in base R as you already mentioned. It drove
>> me
>> bonkers that it creates packages which then fail R CMD check, so I wrote a
>> wrapper package (pkgKitten) with another helper function (kitten()) which
>> calls the base R helper and then cleans up it---but otherwise remains
>> faithful to it.
>
>
> Failing R CMD check isn't a big deal:  you want to be reminded to edit those
> incomplete help files.  But I think I recall that you couldn't even build
> the package that package.skeleton() created, and that indeed would be
> irritating, especially if you had a lot of functions so you had a lot of
> cleanup to do.  I don't know if that's still true because I generally use
> RStudio to create the initial package structure rather than calling
> package.skeleton myself.

Personally, I think the biggest problem with package.skeleton() is
that it assumes that the source of truth is objects in an environment.
This seems the wrong way around to me.

Hadley

-- 
http://hadley.nz

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Hadley Wickham]

On Tue, Jan 30, 2018 at 4:55 PM, Duncan Murdoch
 wrote:
> On 30/01/2018 4:30 PM, Kenny Bell wrote:
>>
>> In response to Duncan regarding the use of roxygen2 from the point of view
>> of a current user, I believe the issue he brings up is one of correlation
>> rather than causation.
>
>
> Could be.  However, I think editing comments in a .R file is a bit harder
> than editing text in a .Rd file, so I think the format discourages editing.
> I think it does make it easier to pass R CMD check the first time, but I
> don't think you should be satisfied with that.

One counter-point: I find it much easier to remember to update the
documentation when you update the code, if the code and the
documentation are very close together. I think mingling code and
documentation in the same file does add a subtle pressure to write
shorter docs, but I'm not entirely sure that's a bad thing - for long
form writing, vignettes are a much better solution anyway (since you
often want to mingle code and explanation).

Personally, I don't find writing in comments any harder than writing
in .Rd files, especially now that you can write in markdown and have
it automatically translated to Rd formatting commands.  And on the
negative side of Rd, I find it frustrating to have to copy and paste
the function definition to the usage section every time I modify an
argument. It just feels like unnecessary busywork that the computer
should be able to do for me (although I do understand why it is not
possible).

>> Writing my first piece of R documentation was made much easier by using
>> roxygen2, and it shallowed the learning curve substantially.
>
> I'm not completely up to date on Roxygen2 these days:  can you do some pages
> in Rd, others in Roxygen?  That's not quite as good as being able to switch
> back and forth, but it would allow you to start in Roxygen, then gradually
> move to Rd when editing there was easier.

Yes, that's possible, and to protect you in mixed environment,
roxygen2 will never overwrite a file that it did not itself create.

Hadley

-- 
http://hadley.nz

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 30/01/2018 4:12 PM, Dirk Eddelbuettel wrote:


Mehmet,

That is a loaded topic, not unlikely other topics preoccupying us these days.

There is package.skeleton() in base R as you already mentioned. It drove me
bonkers that it creates packages which then fail R CMD check, so I wrote a
wrapper package (pkgKitten) with another helper function (kitten()) which
calls the base R helper and then cleans up it---but otherwise remains
faithful to it.


Failing R CMD check isn't a big deal:  you want to be reminded to edit 
those incomplete help files.  But I think I recall that you couldn't 
even build the package that package.skeleton() created, and that indeed 
would be irritating, especially if you had a lot of functions so you had 
a lot of cleanup to do.  I don't know if that's still true because I 
generally use RStudio to create the initial package structure rather 
than calling package.skeleton myself.


Duncan Murdoch



These days pkgKitten defaults to creating per-package top-level help page
that just references content from DESCRIPTION via a set of newer Rd macros as
I find that helps keeping them aligned. The most recent example of mine is
   https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
I use either this function or the RStudio template helper all the time.

And similarly, other people written similar helpers. You may get other pointers.

And every couple of months someone writes a new tutorial about how to write a
first package. Then social media goes gaga and we get half a dozen blog posts
where someone celebrates finding said tutorial, reading it and following
through with a new package.

And many of us taught workshops on creating packages. There is a lot of
material out here, though lots of this material seems to be entirely ignorant
of what came before it.

And there has been lots, including Fritz's tutorial from a decade ago:

 https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
 https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf

So I'd recommend you just experiment and set up your own helpers. After all
the rule still holds: Anything you do more than three times should be a
function, and every function should be in a package. So customize _your_
function to create your package.

Dirk



__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 30/01/2018 4:30 PM, Kenny Bell wrote:

In response to Duncan regarding the use of roxygen2 from the point of view
of a current user, I believe the issue he brings up is one of correlation
rather than causation.


Could be.  However, I think editing comments in a .R file is a bit 
harder than editing text in a .Rd file, so I think the format 
discourages editing.  I think it does make it easier to pass R CMD check 
the first time, but I don't think you should be satisfied with that.


What would probably change my mind would be a two-way (or multi-way) 
tool:  it takes input in Roxygen comments or Rd files (or something 
else), and produces another format.  Then I'd probably choose to write 
the first pass in Roxygen, and convert to Rd for editing.  Other people 
might go in the opposite direction.  Or someone might write a fancy 
WYSIWYG editor for people who like that style of editing.


A couple of years ago I was hoping someone would figure out a way to 
create help page input in R Markdown, but I think that's tricky because 
of the lack of semantic markup there.  There *was* a project last year 
to work on other input methods; I dropped out before it got very far, 
and I don't know its current status.




Writing my first piece of R documentation was made much easier by using
roxygen2, and it shallowed the learning curve substantially.


I'm not completely up to date on Roxygen2 these days:  can you do some 
pages in Rd, others in Roxygen?  That's not quite as good as being able 
to switch back and forth, but it would allow you to start in Roxygen, 
then gradually move to Rd when editing there was easier.




What Duncan may be observing is a general tendency of roxygen2 users to
write overly concise documentation. However, I believe this to be caused by
an omitted variable - likely the tendency of roxygen2 users to want outputs
quickly. I can't see anything in roxygen2 that might suggest a causal link
but I'd be interested in hearing specific examples.


I don't know about that.  *Everyone* wants output quickly.

Duncan Murdoch



FWIW, I've also heard the same documentation criticism leveled at R in
general (mostly from Stata and MATLAB users).

Kenny

On Wed, Jan 31, 2018, 10:12 AM Dirk Eddelbuettel  wrote:



Mehmet,

That is a loaded topic, not unlikely other topics preoccupying us these
days.

There is package.skeleton() in base R as you already mentioned. It drove me
bonkers that it creates packages which then fail R CMD check, so I wrote a
wrapper package (pkgKitten) with another helper function (kitten()) which
calls the base R helper and then cleans up it---but otherwise remains
faithful to it.

These days pkgKitten defaults to creating per-package top-level help page
that just references content from DESCRIPTION via a set of newer Rd macros
as
I find that helps keeping them aligned. The most recent example of mine is
   https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
I use either this function or the RStudio template helper all the time.

And similarly, other people written similar helpers. You may get other
pointers.

And every couple of months someone writes a new tutorial about how to
write a
first package. Then social media goes gaga and we get half a dozen blog
posts
where someone celebrates finding said tutorial, reading it and following
through with a new package.

And many of us taught workshops on creating packages. There is a lot of
material out here, though lots of this material seems to be entirely
ignorant
of what came before it.

And there has been lots, including Fritz's tutorial from a decade ago:

 https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
 https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf

So I'd recommend you just experiment and set up your own helpers. After all
the rule still holds: Anything you do more than three times should be a
function, and every function should be in a package. So customize _your_
function to create your package.

Dirk

--
http://dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel



[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel



__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Suzen, Mehmet]

On 30 January 2018 at 21:31, Cook, Malcolm  wrote:
>
> I think you want to see the approach to generating a skeleton from a single 
> .R file presented in:
>
> Simple and sustainable R packaging using inlinedocs 
> http://inlinedocs.r-forge.r-project.org/
>
> I have not used it in some time but found it invaluable when I did.

For the record, the package has a JSS article as well:

https://www.jstatsoft.org/article/view/v054i06


Best,
-m

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Suzen, Mehmet]

Dear All,

Thank you for all valuable input and sorry for the off-topic for the
list. I will try R-pkg-devel for further related questions.   I was
actually after "one-go" auto-documentation in-line or out of comments
from a single file/environment in a similar spirit to
'package.skeleton or an extension of it. My take-home message or
summary from all responses do far.

* Regarding documentation;Duncan Murdoch's  wisdom "...to get good
stuff in the help page, you need just as much work as in writing the
.Rd file directly..". So there is no silver bullet in terms of
auto-documentation, I gather, especially for considering if one uses
more complex constructs, S4/S6 classes or Rcpp code behind.On the
other hand, roxgen2 being the most comprehensive solution.

* Lightweight solution to try out before moving to RStudio fully. I
will give a try Dirk's 'pkgKitten' and 'inlinedocs' Malcolm mentioned.

Interestingly, responses have reminded me Larry Wall's quote
(https://en.wikipedia.org/wiki/There%27s_more_than_one_way_to_do_it),
which I think really applies to R more than any language I encounter
so far, from different class systems to different time-series
representations, so richly democratised.

Many regards,
Mehmet


On 30 January 2018 at 17:00, Suzen, Mehmet  wrote:
> Dear R developers,
>
> I am wondering what are the best practices for developing an R
> package. I am aware of Hadley Wickham's best practice
> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
> years ago there were some tools for generating a package out of a
> single file, such as using package.skeleton, but no auto-generated
> documentation. Do you know a way to generate documentation and a
> package out of single R source file, or from an environment?
>
> Many thanks,
> Mehmet

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Kenny Bell]

In response to Duncan regarding the use of roxygen2 from the point of view
of a current user, I believe the issue he brings up is one of correlation
rather than causation.

Writing my first piece of R documentation was made much easier by using
roxygen2, and it shallowed the learning curve substantially.

What Duncan may be observing is a general tendency of roxygen2 users to
write overly concise documentation. However, I believe this to be caused by
an omitted variable - likely the tendency of roxygen2 users to want outputs
quickly. I can't see anything in roxygen2 that might suggest a causal link
but I'd be interested in hearing specific examples.

FWIW, I've also heard the same documentation criticism leveled at R in
general (mostly from Stata and MATLAB users).

Kenny

On Wed, Jan 31, 2018, 10:12 AM Dirk Eddelbuettel  wrote:

>
> Mehmet,
>
> That is a loaded topic, not unlikely other topics preoccupying us these
> days.
>
> There is package.skeleton() in base R as you already mentioned. It drove me
> bonkers that it creates packages which then fail R CMD check, so I wrote a
> wrapper package (pkgKitten) with another helper function (kitten()) which
> calls the base R helper and then cleans up it---but otherwise remains
> faithful to it.
>
> These days pkgKitten defaults to creating per-package top-level help page
> that just references content from DESCRIPTION via a set of newer Rd macros
> as
> I find that helps keeping them aligned. The most recent example of mine is
>   https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd
> I use either this function or the RStudio template helper all the time.
>
> And similarly, other people written similar helpers. You may get other
> pointers.
>
> And every couple of months someone writes a new tutorial about how to
> write a
> first package. Then social media goes gaga and we get half a dozen blog
> posts
> where someone celebrates finding said tutorial, reading it and following
> through with a new package.
>
> And many of us taught workshops on creating packages. There is a lot of
> material out here, though lots of this material seems to be entirely
> ignorant
> of what came before it.
>
> And there has been lots, including Fritz's tutorial from a decade ago:
>
> https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
> https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
>
> So I'd recommend you just experiment and set up your own helpers. After all
> the rule still holds: Anything you do more than three times should be a
> function, and every function should be in a package. So customize _your_
> function to create your package.
>
> Dirk
>
> --
> http://dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Dirk Eddelbuettel]

Mehmet,

That is a loaded topic, not unlikely other topics preoccupying us these days.

There is package.skeleton() in base R as you already mentioned. It drove me
bonkers that it creates packages which then fail R CMD check, so I wrote a
wrapper package (pkgKitten) with another helper function (kitten()) which
calls the base R helper and then cleans up it---but otherwise remains
faithful to it.

These days pkgKitten defaults to creating per-package top-level help page
that just references content from DESCRIPTION via a set of newer Rd macros as
I find that helps keeping them aligned. The most recent example of mine is
  https://github.com/eddelbuettel/prrd/blob/master/man/prrd-package.Rd 
I use either this function or the RStudio template helper all the time.

And similarly, other people written similar helpers. You may get other pointers.

And every couple of months someone writes a new tutorial about how to write a
first package. Then social media goes gaga and we get half a dozen blog posts
where someone celebrates finding said tutorial, reading it and following
through with a new package. 

And many of us taught workshops on creating packages. There is a lot of
material out here, though lots of this material seems to be entirely ignorant
of what came before it.

And there has been lots, including Fritz's tutorial from a decade ago:

https://epub.ub.uni-muenchen.de/6175/  as well as on CRAN as
https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf

So I'd recommend you just experiment and set up your own helpers. After all
the rule still holds: Anything you do more than three times should be a
function, and every function should be in a package. So customize _your_
function to create your package.

Dirk

-- 
http://dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Duncan Murdoch]

On 30/01/2018 11:29 AM, Brian G. Peterson wrote:

On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:

Dear R developers,

I am wondering what are the best practices for developing an R
package. I am aware of Hadley Wickham's best practice
documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
years ago there were some tools for generating a package out of a
single file, such as using package.skeleton, but no auto-generated
documentation. Do you know a way to generate documentation and a
package out of single R source file, or from an environment?


Mehmet,

This list is for development of the R language itself and closely
related tools.  There is a separate list, R-pkg-devel, for development
of packages.

Since you're here, I'll try to answer your question.

package.skeleton can create a package from all the R functions in a
specified environment.  So if you load all the functions that you want
in your new package into your R environment, then call
package.skeleton, you'll have a starting point.

At that point, I would probably recommend moving to RStudio, and using
RStudio to generate markdown comments for roxygen for all your newly
created function files.  Then you could finish off the documentation by
writing it in these roxygen skeletons or copying and pasting from
comments in your original code files.


I'd agree about moving to RStudio, but I think Roxygen is the wrong 
approach for documentation.  package.skeleton() will have done the 
boring mechanical part of setting up your .Rd files; all you have to do 
is edit some content into them.  (Use prompt() to add a new file if you 
add a new function later, don't run package.skeleton() again.)


This isn't the fashionable point of view, but I think it is easier to 
get good documentation that way than using Roxygen.  (It's easier to get 
bad documentation using Roxygen, but who wants that?)


The reason I think this is that good documentation requires work and 
thought.  You need to think about the markup that will get your point 
across, you need to think about putting together good examples, etc.
This is *harder* in Roxygen than if you are writing Rd files, because 
Roxygen is a thin front end to produce Rd files from comments in your .R 
files.  To get good stuff in the help page, you need just as much work 
as in writing the .Rd file directly, but then you need to add another 
layer on top to put in in a comment.  Most people don't bother.


I don't know any packages with what I'd consider to be good 
documentation that use Roxygen.  It's just too easy to write minimal 
documentation that passes checks, so Roxygen users don't keep refining it.


(There are plenty of examples of packages that write bad documentation 
directly to .Rd as well.  I just don't know of examples of packages with 
good documentation that use Roxygen.)


Based on my criticism last week of git and Github, I expect to be called 
a grumpy old man for holding this point of view.  I'd actually like to 
be proven wrong.  So to anyone who disagrees with me:  rather than just 
calling me names, how about some examples of Roxygen-using packages that 
have good help pages with good explanations, and good examples in them?


Back to Mehmet's question:  I think Hadley's book is pretty good, and 
I'd recommend most of it, just not the Roxygen part.


Duncan Murdoch

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Best practices in developing package: From a single file

[Brian G. Peterson]

On Tue, 2018-01-30 at 17:00 +0100, Suzen, Mehmet wrote:
> Dear R developers,
> 
> I am wondering what are the best practices for developing an R
> package. I am aware of Hadley Wickham's best practice
> documentation/book (http://r-pkgs.had.co.nz/).  I recall a couple of
> years ago there were some tools for generating a package out of a
> single file, such as using package.skeleton, but no auto-generated
> documentation. Do you know a way to generate documentation and a
> package out of single R source file, or from an environment?

Mehmet,

This list is for development of the R language itself and closely
related tools.  There is a separate list, R-pkg-devel, for development
of packages.  

Since you're here, I'll try to answer your question.

package.skeleton can create a package from all the R functions in a
specified environment.  So if you load all the functions that you want
in your new package into your R environment, then call
package.skeleton, you'll have a starting point.

At that point, I would probably recommend moving to RStudio, and using
RStudio to generate markdown comments for roxygen for all your newly
created function files.  Then you could finish off the documentation by
writing it in these roxygen skeletons or copying and pasting from
comments in your original code files.

Please address further discussion to the R-pkg-devel list.

Regards,

Brian

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel