R devel - Jan 2018 - Best practices in developing package: From a single file

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-bounces at 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.duncan at
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&entry=gmail&source=g>

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

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

	[[alternative HTML version deleted]]

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

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_Pfaff at 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-bounces at 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.duncan at
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&entry=gmail&source=g>
>
> -----------
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> -------------------------------
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> *****************************************************************
> Confidentiality Note: The information contained in this ...{{dropped:10}}
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

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
<suzen at acm.org>


On 31 January 2018 at 15:51, Pfaff, Bernhard Dr.
<Bernhard_Pfaff at 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-bounces at 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.duncan at
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&entry=gmail&source=g>
>
> -----------
> Biowiskundedagen 2017-2018
> http://www.biowiskundedagen.ugent.be/
>
> -------------------------------
> Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> *****************************************************************
> Confidentiality Note: The information contained in this ...{{dropped:10}}
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

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 <suzen at 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
> <suzen at acm.org>
>
>
> On 31 January 2018 at 15:51, Pfaff, Bernhard Dr.
> <Bernhard_Pfaff at 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-bounces at 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.duncan at 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&entry=gmail&source=g>
> >
> > -----------
> > Biowiskundedagen 2017-2018
> > http://www.biowiskundedagen.ugent.be/
> >
> > -------------------------------
> > Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
> >
> >         [[alternative HTML version deleted]]
> >
> > ______________________________________________
> > R-devel at r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
> > *****************************************************************
> > Confidentiality Note: The information contained in this
...{{dropped:10}}
> >
> > ______________________________________________
> > R-devel at r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>


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

	[[alternative HTML version deleted]]