From mark.vanderloo at gmail.com  Wed Jan 31 14:59:56 2018
From: mark.vanderloo at gmail.com (Mark van der Loo)
Date: Wed, 31 Jan 2018 13:59:56 +0000
Subject: [Rd] Best practices in developing package: From a single file
In-Reply-To: <CAO1zAVZGG33AUWUQ0Sbjaaqf2FSZ3JNsxzvdNHn9sBcYYDL7LQ@mail.gmail.com>
References: <CAPtbhHwLXvdCX+1PJvEAyjWtcaVf=k4kL2fgXNhxLqfBhoJg-Q@mail.gmail.com>
 <1517329742.15543.15.camel@braverock.com>
 <aef83954-b118-6f8f-6d4f-d2a9758121cc@gmail.com>
 <CAO1zAVaHnOthsFc9DGbC2+otAhHJ7qRi4hUZrqk67NFwpr6osA@mail.gmail.com>
 <2d6d82a8-0dc3-0fbe-5b25-8c86c74a1aad@gmail.com>
 <CAO1zAVZGG33AUWUQ0Sbjaaqf2FSZ3JNsxzvdNHn9sBcYYDL7LQ@mail.gmail.com>
Message-ID: <CAOKDuOj01EUf1Phru7CP6k-Cfdh6qjFqDmfcv9i0BGbDfBKzog@mail.gmail.com>

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 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. 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 <jorismeys at gmail.com>:

> On Wed, Jan 31, 2018 at 1:41 PM, Duncan Murdoch <murdoch.duncan at 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 at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

	[[alternative HTML version deleted]]



[Rd] Best practices in developing package: From a single file
Mark van der Loo