On 24/07/2019 6:54 a.m., Martin Maechler wrote:
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.)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.
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 ______________________________________________ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
