[R-pkg-devel] Note on winbuilder-develop

[Duncan Murdoch]

On 24/07/2019 6:54 a.m., Martin Maechler wrote:
>>>>>> Duncan Murdoch
>>>>>>      on Wed, 24 Jul 2019 06:12:35 -0400 writes:
> 
>      > On 24/07/2019 3:08 a.m., Martin Maechler wrote:
>      >>>>>>> Roy Mendelssohn
>      >>>>>>> on Tue, 23 Jul 2019 18:44:24 -0700 writes:
>      >>
>      >> > Thanks, I was looking at the raw files, not the .Rd files.
>      >> > There are \keyword arguments in those file, will have to
>      >> > search to see why they are getting generated.  -Roy
>      >>
>      >> just to rub the obvious into everybody's face ;-) :-D
>      >> { apology for any offence ! } :
>      >>
>      >> If you'd use roxygen only initially and not anymore from then
>      >> on, but rather then would keep hand-editing nicely humanly
>      >> formatted  man/*.Rd  files,
>      >> you would never see this (and quite a few "similar") problems.
> 
>      > I don't think that's a great idea, unless the initial use is basically
>      > no more than using prompt().  If you have comments in your source that
>      > look like help text, and different help text in your Rd file, it's going
>      > to lead to confusion.  I don't think Roxygen is capable of updating your
>      > source file comments when you edit your Rd file.
> 
>      > Duncan Murdoch
> 
> Ok,  now you're triggering me  ... probably I should have
> refrained from that first e-mail  ...
> 
> What I *meant* and failed to say more explicitly:
> 
> I would use roxygen comments for functions I write
> "somewhere", possibly outside a package and I do *not* export (yet?)
> when inside a package.  Once I decide it should become an
> exported function I use the roxygen stuff to create the very
> first version of my help page *AND THEN* delete most of the
> roxygen text comments (maybe leave 2 lines or so) and from then
> on only use *.Rd files, which I keep nicely indented, and even *commented*
> (is that possible at all inside roxygen?), add math
> formula, add examples, enumeration lists, \describe{..} lists
> etc in much more nicely readable form than wrapped inside the
> "roxygen language"  and never go back to using Roxygen there.
> The same with the nicely human-annotated and sorted  NAMESPACE
> file.
To me that seems like too much work.  If I'm writing something that 
needs user comments, I would probably put it in a package, and use 
prompt() to immediately start putting user documentation into an Rd 
file.  (There can also be programmer documentation that belongs in the 
.R file.)

The disadvantage of my approach is that it's a little clunky to handle 
changes to the function signatures.  There's a function Rdpack::reprompt 
that is supposed to update Rd files when the sources change; I should 
probably adopt it as part of my workflow, but I haven't done so.

> 
> As you know, R works from the NAMESPACE and man/*.Rd files
> anyway, and so I don't add an extra translation layer .. and keep
> *.Rd and NAMESPACE files that are both much nicer readable than
> as part of roxygen comments blowing up the size of the *.R
> source files.
> By taking the *.Rd out of the source, I'm much less tempted to
> keep the documentation minimal and almost unuseful, as I see it
> in many packages built using Roxygen..
> 

I agree with you about the value of writing Rd files, and the cost (e.g. 
incorrect Rd files with confusing error messages like Roy found) of 
relying on Roxygen.  But there are lots of people who disagree with us.

Duncan