[R-pkg-devel] Note on winbuilder-develop
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