[Roxygen-devel] Problems with (understanding) 'useRd2', '@example' and processing of DESCRIPTION file

[Janko Thyson]

Dear List, 

Sorry, this is sort of a re-post from this one here:
http://r.789695.n4.nabble.com/Roxygen-question-regarding-use-Rd2-and-creatio
n-of-DESCRIPTION-tt2540553.html#a2540553. But since I did not get any
replies and some time has passed, I hope it's okay to post it in this
special roxygen list again.

I ran into the following two problems while using the package 'roxygen': 

PROLBEM 1 
Is there a list about what roughly happens (or does not happen) when setting
'useRd2=TRUE/FALSE' (as I don't really understand how to make use of this
argument yet)?

I split the relevant R-Code for my package into the following scripts:
classes.R (S4), functions.R ('standard' functions), generics.R (S4),
methods.R (S4). Function package.skeleton() generates Rd-files for all class
defs, function defs etc. in dir 'pkg/man'. So far, so good. Now, I'd like to
run 'roxygenize()' on dir 'pkg' and face the problem that the argument
'use.Rd2' only works for parts of the Rd-files, no matter how it is
specified. Setting it FALSE works for all non-S4 defs, setting it TRUE works
for all S4-defs ('works' in the sense of ending up with non-empty \title{}
in the Rd-files). However, both types of defs are in 'pkg/man' or 'pkg/R',
respectivley. 

I implemented a workaround in which each of the four scripts is addressed
separately by package.skeleton() and roxygenize(). The resulting Rd-files
are stored in temp dirs (e.g. 'pkg/tmp_classes', 'pgk/tmp_functions' etc.)
and are merged to 'pkg/man' at the very end of the process. But I figured
there must be a better or at least more elegant way to do this. Any hints? 

I should mention that not all of my defs (be it non-S4 or S4) are already
prepended with roxygen-code (related to this post
http://stackoverflow.com/questions/2316356/can-roxygen-ignore-non-user-funct
ions), yet the workaround creates non-empty \title{} for all Rd-files (which
is enough for those scripts). Is this also possible by running
package.skelleton() and roxygenize() just once? 


PROBLEM 2 
I tried using '@example' to specifiy the path to a script containing example
code for an arbitrary function. Yet, this tag seems not to be processed
(neither  'useRd2=TRUE/FALSE' works). Any ideas? Also, does stuff like
\dontrun{}, \dontshow{} etc. work for code that is tagged with '@examples'
(the "more manual" way of specifying examples with roxygen) or do I simply
have to turn on '--no-examples' on in R CMD check?

PROBLEM 3
Even though I followed the roxygen vignette closely and also had a look at 
the webvis package as suggested here 
http://stackoverflow.com/questions/3086081/how-do-you-write-your-package-doc
umentation, I still cannot reproduce a DESCRIPTION file that reflects the 
specifications I made via the part of the roxygen-code that is related to 
stating the package title, author etc. The outcome in the Rd file 
'<pkg_name>-package.Rd' is fine, but the DESCRIPTION file itself still looks

like the dummy created by package.skelleton. Am I doing something wrong 
here? 

In case the problems I'm facing are not related to errors on my side but
represent some sort of bugs, I'd be happy to contribute my workarounds that
might help the developers fixing the issues.

Thanks very much for any suggestions, 
Janko