On 31/01/2018 8:59 AM, Mark van der Loo wrote:
I fully agree with Joris and Hadley on roxygen2.
Additionally:
I wrote and published my first package before roxygen (or roxygen2) was
available. I found editing .Rd extremely terse (especially when code is
updated). For example, the fact that there are no spaces allowed between
} and { in \param{}{} has hurt my brain quite a few times, especially
There's no \param macro in Rd. You're probably thinking of \item{}{} or
\section{}{}, or some other two-arg macro. There aren't very many of
them, but there are a few.
If it really is \item, then the error message you get would look
something like this:
Warning: bad markup (extra space?) at foo.Rd:15:16
That's column 16 of line 15. I'm not sure this guess is right, because
that message does seem pretty informative.
There are also a couple of 1 or 2 argument macros (\eqn and \deqn),
where the space would make the parser think you were using the 1
argument version. I think that's the same behaviour as LaTeX, which the
Rd format is loosely based on.
since R CMD check did not give any useful error messages about it. For
me it is a signal that the Rd parser is rather primitive.
Originally the format was defined in a really ad hoc way: help pages
were formed not by parsing the Rd file, but by applying a sequence of
substitutions to it. I wrote a parser following the usual R policy of
trying not to break too much existing code. This wasn't easy because
the format had grown into something fairly awful, but I wouldn't call it
primitive. At the time I was really hoping someone else would propose
something better, but I don't think that ever happened.
Duncan Murdoch
On the other
hand Roxygen2 now usually gives pretty good error messages when I syntax
error something.
Also, the 'parent' of roxygen is Doxygen, which was already widely used
(also by me) in the C/C++ community before roxygen was published. I
cannot remember anyone ever complaining about C/C++ documentation
deteriorating because of Doxygen.
-Mark
Op wo 31 jan. 2018 om 14:02 schreef Joris Meys <jorism...@gmail.com
<mailto:jorism...@gmail.com>>:
On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch
<murdoch.dun...@gmail.com <mailto:murdoch.dun...@gmail.com>>
wrote:
> On 31/01/2018 6:33 AM, Joris Meys wrote:
>
> 3. given your criticism, I'd like your opinion on where I can
improve the
>> documentation of
https://github.com/CenterForStatistics-UGent/pim. I'm
>> currently busy updating the help files for a next release on
CRAN, so your
>> input is more than welcome.
>>
>
> After this invitation I sent some private comments to Joris. I
would say
> his package does a pretty good job of documentation; it isn't the
kind of
> Roxygen-using package that I was complaining about. So I will
say I have
> received an example of a Roxygen-using package that
> has good help pages.
>
Thank you for the nice compliment and the valuable tips.
--
Joris Meys
Statistical consultant
Department of Data Analysis and Mathematical Modelling
Ghent University
Coupure Links 653, B-9000 Gent (Belgium)
<https://maps.google.com/?q=Coupure+links+653,%C2%A0B-9000+Gent,%C2%A0Belgium&entry=gmail&source=g>
-----------
Biowiskundedagen 2017-2018
http://www.biowiskundedagen.ugent.be/
-------------------------------
Disclaimer : http://helpdesk.ugent.be/e-maildisclaimer.php
[[alternative HTML version deleted]]
______________________________________________
R-devel@r-project.org <mailto:R-devel@r-project.org> mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
