>>>>> 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
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
