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

[Martin Maechler]

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

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

[... end of trigger]

Martin