[Rd] Please explain your workflow from R code -> package -> R code -> package

[Duncan Murdoch]

On 09/09/2011 12:38 PM, Paul Johnson wrote:
> Hi,
>
> I'm asking another one of those questions that would be obvious if I
> could watch your work while you do it.
>
> I'm having trouble understanding the workflow of code and package maintenance.
>
> Stage 1.  Make some R functions in a folder.  This is in a Subversion repo
>
> R/trunk/myproject
>
> Stage 2. Make a package:
>
> After the package.skeleton, and R check, I have a new folder with the
> project in it,
>
> R/trunk/myproject/mypackage
>    DESCRIPTION
>    man
>    R
>
> I to into the man folder and manually edit the Rd files. I don't
> change anything in the R folder because I think it is OK so far.
>
> And eventually I end up with a tarball mypackage_1.0.tar.gz.
>
> Stage 3. How to make the round trip? I add more R code, and
> re-generate a package.
>
> package.skeleton obliterates the help files I've already edited.

You should only run it once.  After that, add your code by editing *.R 
files in the R directory, sourcing them, and generate *.Rd files using 
prompt().  As Dirk said, run R CMD check when you think you're done, and 
it will point out how wrong you are.
> So keeping the R code in sync with the documentation appears to be a hassle.

If you write the *.Rd file before (like Spencer) or soon after writing 
the code, then design errors will usually stick out at you, and you can 
modify the functions.  If you keep your functions small, you'll get them 
working early, and won't have a lot of problems keeping them in sync 
with the docs, because they won't change much once you get them right.

Duncan Murdoch

> In other languages, I've seen to write the documentation inside the
> code files and then post-process to make the documentation.  Is there
> a similar thing for R, to unify the R code development and
> documentation/package-making process?
>
> pj
>