From murdoch.duncan at gmail.com  Fri Feb  2 13:17:18 2018
From: murdoch.duncan at gmail.com (Duncan Murdoch)
Date: Fri, 2 Feb 2018 07:17:18 -0500
Subject: [Rd] Best practices in developing package: From a single file
In-Reply-To: <CADwqtCNrMRY=TJnP7cW59+3z5VTJkVFkSYAf0may1qTk2E0Zpg@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>
 <FCD9A33C859ACC469587CB09DD5C6C7132024B84@GBLONXMB13.corp.amvescap.net>
 <CAPtbhHzGAT9LKC-kkwWQQBdBsMdsirq=0UeZRGb5Ack5rPPX9w@mail.gmail.com>
 <CADwqtCO3Z7vp2TNJLBXpdwnqYyzH4vEzSeXieOSSjsyebojnhA@mail.gmail.com>
 <3A690EC2-7022-4C89-B607-2A9E84EA5862@rstudio.com>
 <CADwqtCNrMRY=TJnP7cW59+3z5VTJkVFkSYAf0may1qTk2E0Zpg@mail.gmail.com>
Message-ID: <41bfcd9a-9a86-eec5-cb2d-c8d4cd86fe23@gmail.com>

On 01/02/2018 12:20 PM, Gabriel Becker wrote:
[ lots deleted...]

> Or perhaps you could imagine two help systems, akin to --help and man for
> command line tools, one of which is minimalist showing usage, etc,
> generated by roxygen comments, and one of which is much more extensive, and
> not tied to (what could be extremely large) comments in the same .R file as
> the code.

I think the input method and output form should be orthogonal.  Several 
front ends already implement minimalist help (e.g. RStudio displays the 
usage and description sections from the help page).

I'd rather have the help info coming from a separate file; other people 
apparently prefer to put it in the .R file.  I think both methods should 
be supported.  It makes sense to me to get both types of info from one 
place, but the author should be able to choose where that is.

Duncan Murdoch

P.S.  I've been playing around with Georgi Boshnakov's Rdpack package, 
putting together an RStudio plug-in to make usage updates trivial.  If 
anyone wants to try it out it's on my Github page for now 
(dmurdoch/Rdpack), but once it's usable, Georgi has said he will merge 
it back into his.



[Rd] Best practices in developing package: From a single file
Duncan Murdoch