[Roxygen-devel] Roxygen comments

[Peter Danenberg]

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.

>   * 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().

>   * What are the line breaking rules? Can I break a line wherever I like?

\newline seems to work.

>   * 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_?

>   * What is the @export tag used in some of the examples?

It collects the exported functions and includes them in the NAMESPACE
file.

>   * 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.

>   * It's not obvious that you need to look in make.Rd.roclet to get
> the documentation about valid tags.  Perhaps an alias?  Individual doc
> pages for each tag would be good too - then you could give more
> examples.
>
>   * It would be helpful if ?roxygen pointed to something useful. It's
> the first thing many people (i.e. me) will try

Great ideas.

>   * 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.

>   * 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.

>   * 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?