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
mailto: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)



---
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] CRAN indices out of whack (for at least macOS)

[Uwe Ligges]

Thanks,
Uwe


On 31.01.2018 20:08, Simon Urbanek wrote:

Dirk,

yes, thanks, the edge server that serves the Mac binaries to CRAN has run out 
of disk space (due to size of CRAN itself) so the sync was incomplete.
It is fixed now -- you can try by using the macos master server as mirror: 
https://r.research.att.com/ and it will propagate through other mirrors as 
usual.

Thanks,
Simon





On Jan 31, 2018, at 1:34 PM, Dirk Eddelbuettel  wrote:


Bumping this as we now have two more issue tickets filed and a fresh SO
question.

Is anybody looking at this? Simon?

Dirk

On 30 January 2018 at 15:19, Dirk Eddelbuettel wrote:
|
| I have received three distinct (non-)bug reports where someone claimed a
| recent package of mine was broken ... simply because the macOS binary was not
| there.
|
| Is there something wrong with the cronjob providing the indices? Why is it
| pointing people to binaries that do not exist?
|
| Concretely, file
|
|   https://cloud.r-project.org/bin/macosx/el-capitan/contrib/3.4/PACKAGES
|
| contains
|
|   Package: digest
|   Version: 0.6.15
|   Title: Create Compact Hash Digests of R Objects
|   Depends: R (>= 2.4.1)
|   Suggests: knitr, rmarkdown
|   Built: R 3.4.3; x86_64-apple-darwin15.6.0; 2018-01-29 05:21:06 UTC; unix
|   Archs: digest.so.dSYM
|
| yet the _same directory_ only has:
|
|   digest_0.6.14.tgz   15-Jan-2018 21:36   157K
|
| I presume this is a temporary accident.
|
| We are all spoiled by you all providing such a wonderfully robust and
| well-oiled service---so again big THANKS for that--but today something is out
| of order.
|
| Dirk
|
| --
| http://dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org
|
| __
| R-devel@r-project.org mailing list
| https://stat.ethz.ch/mailman/listinfo/r-devel

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



__
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] bug [methods]: double execution of `insertSource` within the same session does not work

[Michael Lawrence]

The issue should be resolved in R-devel. It was actually deeper and more
important than this obscure insertSource() function. names() was not doing
the right thing on S4 objects derived from "environment".

On Mon, Jan 29, 2018 at 11:02 AM, Michael Lawrence 
wrote:

> Thanks, I will fix this.
>
> On Mon, Jan 29, 2018 at 8:06 AM, Demetrio Rodriguez T. <
> demetrio.rodrigue...@gmail.com> wrote:
>
>> Hello everyone,
>>
>>
>> I hope this reaches someone at all. It's my first bug report to the
>> R-core,
>> and, apparently, bugzilla is locked from new reports for now.
>>
>> I was using `methods::insertSource` to debug and successfully fix another
>> package, until it suddenly stopped working. I figured out, that it is
>> because I am using it on the same function multiple times within one
>> session. It also produces warnings even during the first call, but somehow
>> still works. Below I provide a reproducible example:
>>
>> SETUP:
>> ```bash
>> demetrio@laptop:[folder_structure]/Bugreports/methods_insertSource$ ls -a
>> .  ..  gmapsdistance_fix.R  methods_insertSource.R
>> ```
>>
>> file `gmapsdistance_fix.R`
>> ```R
>> gmapsdistance = function(param) {
>> print('I am a bug report, my params are:')
>> print(param)
>> }
>> ```
>>
>>
>> file `methods_insertSource.R`
>> ```R
>> library(gmapsdistance)  # works with any package
>>
>> methods::insertSource('gmapsdistance_fix.R',
>> package = 'gmapsdistance',
>> functions = 'gmapsdistance',
>> force = T
>> )
>> buggy = gmapsdistance('Works?')
>> ```
>>
>>
>> TO REPRODUCE:
>> in that directory `R --vanilla` then
>> ```R
>> > source('methods_insertSource.R')
>> Modified functions inserted through trace(): gmapsdistance
>> [1] "I am a bug report, my params are:"
>> [1] "Works?"
>> Warning message:
>> In methods::insertSource("gmapsdistance_fix.R", package =
>> "gmapsdistance",
>> :
>>   cannot insert these (not found in source): "gmapsdistance"
>> # Works, but gives the warning that it does not
>>
>> # repeat:
>> > source('methods_insertSource.R')
>> Error in assign(this, thisObj, envir = envwhere) :
>>   cannot change value of locked binding for 'gmapsdistance'
>> In addition: Warning message:
>> In methods::insertSource("gmapsdistance_fix.R", package =
>> "gmapsdistance",
>> :
>>   cannot insert these (not found in source): "gmapsdistance"
>>
>> # does not work, and gets even more confusing: so is it that the object is
>> not find, or is it about a locked object?
>> ```
>>
>> I think it's a bug.
>>
>> - BUG REPORT END 
>>
>>
>> I looked into it a bit myself, in case you are interested:
>>
>> ```R
>> # lines 20-22
>> if (is(source, "environment"))
>> env <- source
>> else env <- evalSource(source, package, FALSE)
>> # We're in the second case I guess
>>
>> # Browse[2]> env
>> # Object of class "sourceEnvironment"
>> # Source environment created  2017-12-01 05:19:51
>> # For package "gmapsdistance"
>> # From source file "gmapsdistancefix.R"
>>
>>
>> # later, before line 52:
>> x = env
>> Browse[2]> package
>> [1] "gmapsdistance"
>>
>> # evaluate 52
>> packageSlot(env) <- package
>>
>> # objects x and env are still identical
>> # Browse[2]> class(env)
>> # [1] "sourceEnvironment"
>> # attr(,"package")
>> # [1] "methods"
>> # Browse[2]> class(x)
>> # [1] "sourceEnvironment"
>> # attr(,"package")
>> # [1] "methods"
>>
>> # Browse[2]> env
>> # Object of class "sourceEnvironment"
>> # Source environment created  2017-12-01 05:19:51
>> # For package "gmapsdistance"
>> # From source file "gmapsdistancefix.R"
>> # Browse[2]> x
>> # Object of class "sourceEnvironment"
>> # Source environment created  2017-12-01 05:19:51
>> # For package "gmapsdistance"
>> # From source file "gmapsdistancefix.R"
>>
>> # so:
>> Browse[2]>  names(env)
>> NULL
>>
>> # which is why 53-60 do not work:
>> allObjects <- names(env)
>> if (!missing(functions)) {
>> notThere <- is.na(match(functions, allObjects))
>> if (any(notThere)) {
>> warning(gettextf("cannot insert these (not found in source): %s",
>> paste("\"", functions[notThere], "\"", sep = "",
>> collapse = ", ")), domain = NA)
>> }
>> }
>> ```
>>
>> Looking forward to your feedback!
>>
>> Cheers,
>> Demetrio
>>
>> [[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] CRAN indices out of whack (for at least macOS)

[Simon Urbanek]

Dirk,

yes, thanks, the edge server that serves the Mac binaries to CRAN has run out 
of disk space (due to size of CRAN itself) so the sync was incomplete.
It is fixed now -- you can try by using the macos master server as mirror: 
https://r.research.att.com/ and it will propagate through other mirrors as 
usual.

Thanks,
Simon




> On Jan 31, 2018, at 1:34 PM, Dirk Eddelbuettel  wrote:
> 
> 
> Bumping this as we now have two more issue tickets filed and a fresh SO
> question.
> 
> Is anybody looking at this? Simon?
> 
> Dirk
> 
> On 30 January 2018 at 15:19, Dirk Eddelbuettel wrote:
> | 
> | I have received three distinct (non-)bug reports where someone claimed a
> | recent package of mine was broken ... simply because the macOS binary was 
> not
> | there.
> | 
> | Is there something wrong with the cronjob providing the indices? Why is it
> | pointing people to binaries that do not exist?
> | 
> | Concretely, file
> | 
> |   https://cloud.r-project.org/bin/macosx/el-capitan/contrib/3.4/PACKAGES
> | 
> | contains
> | 
> |   Package: digest
> |   Version: 0.6.15
> |   Title: Create Compact Hash Digests of R Objects
> |   Depends: R (>= 2.4.1)
> |   Suggests: knitr, rmarkdown
> |   Built: R 3.4.3; x86_64-apple-darwin15.6.0; 2018-01-29 05:21:06 UTC; unix
> |   Archs: digest.so.dSYM
> | 
> | yet the _same directory_ only has:
> | 
> |   digest_0.6.14.tgz 15-Jan-2018 21:36   157K
> | 
> | I presume this is a temporary accident.
> | 
> | We are all spoiled by you all providing such a wonderfully robust and
> | well-oiled service---so again big THANKS for that--but today something is 
> out
> | of order.
> | 
> | Dirk
> | 
> | -- 
> | http://dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org
> | 
> | __
> | R-devel@r-project.org mailing list
> | https://stat.ethz.ch/mailman/listinfo/r-devel
> 
> -- 
> 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] CRAN indices out of whack (for at least macOS)

[Dirk Eddelbuettel]

Bumping this as we now have two more issue tickets filed and a fresh SO
question.

Is anybody looking at this? Simon?

Dirk

On 30 January 2018 at 15:19, Dirk Eddelbuettel wrote:
| 
| I have received three distinct (non-)bug reports where someone claimed a
| recent package of mine was broken ... simply because the macOS binary was not
| there.
| 
| Is there something wrong with the cronjob providing the indices? Why is it
| pointing people to binaries that do not exist?
| 
| Concretely, file
| 
|   https://cloud.r-project.org/bin/macosx/el-capitan/contrib/3.4/PACKAGES
| 
| contains
| 
|   Package: digest
|   Version: 0.6.15
|   Title: Create Compact Hash Digests of R Objects
|   Depends: R (>= 2.4.1)
|   Suggests: knitr, rmarkdown
|   Built: R 3.4.3; x86_64-apple-darwin15.6.0; 2018-01-29 05:21:06 UTC; unix
|   Archs: digest.so.dSYM
| 
| yet the _same directory_ only has:
| 
|   digest_0.6.14.tgz   15-Jan-2018 21:36   157K
| 
| I presume this is a temporary accident.
| 
| We are all spoiled by you all providing such a wonderfully robust and
| well-oiled service---so again big THANKS for that--but today something is out
| of order.
| 
| Dirk
| 
| -- 
| http://dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org
| 
| __
| R-devel@r-project.org mailing list
| https://stat.ethz.ch/mailman/listinfo/r-devel

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

[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  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
> 
>
>
> On 31 January 2018 at 15:51, Pfaff, Bernhard Dr.
>  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)  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@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] Why R should never move to git

[Suzen, Mehmet]

On 31 January 2018 at 16:18, Barry Rowlingson
 wrote:
>>
>
> Let the record also state that *gitlab* is an open source project and can be
> downloaded and self-hosted, like gogs, but unlike github.


Good to know. Nice one: https://github.com/gitlabhq/gitlabhq

Best,
-m


> PS I've been running a gitlab instance for my group for a couple of years on
> a private server.

Is it a smooth ride so far?

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



On 31 January 2018 at 15:51, Pfaff, Bernhard Dr.
 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 
> 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
> *
> 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.
 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 
> 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
> *
> 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] Why R should never move to git

[Barry Rowlingson]

On Tue, Jan 30, 2018 at 11:07 PM, Suzen, Mehmet 
wrote:

> This might be off topic, but if R-core development ever moves to git,
> I think it would make sense to have its own git service hosted by a
> university, rather than using
> github or gitlab. It is possible via https://gogs.io/ project.
>
> Just for the record.
>
>
Let the record also state that *gitlab* is an open source project and can
be downloaded and self-hosted, like gogs, but unlike github.

Barry

PS I've been running a gitlab instance for my group for a couple of years
on a private server.

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

[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 
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
*
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&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@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 
mailto: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'

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 old man for holding this poin