[Roxygen-devel] Roxygen comments

[hadley wickham]

On Wed, Jan 21, 2009 at 2:47 AM, Peter Danenberg <pcd at roxygen.org> wrote:
> Thanks for the excellent comments, Hadley.
>
>>   * A description of the basic philosophy: creates a new package
>> elsewhere.  Personally, I'd prefer if it could operate in place (can
>> it? the documentation isn't clear) - it makes it easier to test, and
>> to collaborate with others who don't want to worry about running
>> roxygen.
>
> R CMD roxygen has a -d (destructive) option; which is the same as
> passing copy.package = FALSE and overwrite = TRUE to roxygenize.

Destructive sounds a bit scary - it would be nice to have note to
confirm that it only destroys previous documentation.

>>   * R CMD roxygen doesn't work for me.
>
> I'm relying on several hacks to install pkg/src/roxygen which are
> apparently fragile; I've been looking for another package to use as an
> example.
>
>>   * Need to list the basic tags
>
> Good idea.
>
>>   * When you generate a call graph, where does it go?
>
> Currently in ${PKG}/inst/doc, so that they're indexable by the
> help.start().

Ah ok.  What do you imagine people using the call graph for?

>>   * What are the line breaking rules? Can I break a line wherever I like?
>
> \newline seems to work.

I meant in the tags themselves - i.e. it would be useful to have a
note saying that newlines are ignored unless they preceed a @tag, or
whatever the real rule is.

>>   * Generally, what can the contents of a tag be?  Do I use the
>> standard Rdoc tags?  If so, it would be helpful to include these in
>> the vignette so it's self contained and you don't need to look
>> elsewhere.
>
> Yes, you can use Rd tags; you mean basically a resume of "Writing R
> documentation files" from _Writing R Extensions_?

Yes, but with more examples - e.g. I can never remember the syntax for
describe or itemize.

>>   * What is the @export tag used in some of the examples?
>
> It collects the exported functions and includes them in the NAMESPACE
> file.

Ok, that's a nice idea.

>>   * Is there a generic method for including chunks of text like there
>> is for example code with @example?  This would be particularly useful
>> if it was just treated like a chunk of text and so could contain other
>> @tags (like a text preprocessor)
>
> We support a @section tag which takes a title and arbitrary text.

I meant including the same text in multiple places in the
documentation - i.e. when you have a whole lot of functions around a
common theme, it's useful to have a common description, and rather
than having to copy and paste it into every location it would be nice
to have a single location.

>>   * A common use case for alias is to document multiple functions in a
>> single place.  Some way of describing this so that usage was inserted
>> automatically would be helpful.  An example of how to not document a
>> function would work well here too.
>
> Weren't we working on that, Manuel, vis a vis @deprecated, etc.?
>
>>   * If you accidentally use @example instead of @examples you get an
>> unintuitive error message: In file(con, "r") : cannot open file
>> 'holes1d <- guided_tour(holes, 1)...'
>
> @examples is supposed to point to an external file containing
> examples; I'll remedy the error message.

Great - it's easy to to miss that extra s.

>
>>   * I get this warning when roxygenising: Warning in load.dependencies() :
>>     Package(s) 'R', 'tourr' wouldn't load; callgraphs might be incomplete.
>
> In order to do static callgraphs, the package itself has to be
> loadable; that's unfortunate in the sense that you may have to install
> the package before generating the docs.

Did you see the recent message to R help on this topic?  It might be
good to add a little more explanation to the warning.

>>   * If the R CMD check scripts move to R code, it would be great to
>> run them as part of the roxygenize process.  Combined with the
>> previous request this would be incredibly time saving because my
>> package checking processing currently works something like this:
>> discover example is broken, fix example, rerun roxygen, wait a minute,
>> rerun R CMD check, wait 5 minutes, discover another example is broken,
>> ...
>
> In the sense that it runs a full R CMD check, or tries to do something
> piece-wise based on the file you're editing?

Piece-wise.  Just running all the examples for the edited file would
be really really useful.

Hadley


-- 
http://had.co.nz/