[rkward-devel] roxygen2 docs for rkward package

[meik michalke]

hi thomas,

Am Mittwoch, 7. September 2011, 10:03:30 schrieb Thomas Friedrichsmeier:
> could you give some advice on what this means for maintaining the docs?
> Will the roxygen comments become the primary source of documentation? Or
> will the Rd files remain the primary documentation, and comments will be
> updated using Rd2roxygen?

i would suggest using roxygen from here on, because it's harder to forget to 
update the docs if they're in the same file, and it automatically does some 
checking. i used Rd2roxygen to initially convert the existing docs. it's 
rather pointless to repeat that agein and again ;-)

the workflow would be like
 - update the code
 - update the roxygen comments
 - call roxygenize() to create the updated Rd files
 - (build a package)

> I also note that a bunch of functions did not receive roxygen comments

see, that's what i mean :-) it becomes more obvious what is documented and 
what not...

[Rd2roxygen actually missed one Rd file on a graphincs function, all others 
were converted. i'll have to correct for that yet.]

> (apparently those which are documented together with other functions,
> instead of on separate help pages). Is there a good way to deal with
> these? Does roxygen support documenting multiple functions on a single
> page at all?

roxygen doesn't need to create docs for everything, and it can create one doc 
file for a group of things (mostly by specifying @aliases an/or @rdname). as 
long as you don't need a namespace all is pretty easy. once you do, you must 
at least provide each public function with an @export tag. but still you can 
have parts undocumented. it will just only create docs if they were specified.

note that the present comments work with roxygen2 (which is a rewrite, a 
little simpler to work with and *much* faster when working), and not the old 
roxygen. the new version still has some small bugs or missing features, like 
not knowing @slot for S4 classes or quoting "method<-" methods wrong, but that 
doesn't matter here, and it's recommended by the developers nonetheless.


viele grüße :: m.eik

-- 
  dipl. psych. meik michalke
  abt. f"ur diagnostik und differentielle psychologie
  institut f"ur experimentelle psychologie
  heinrich-heine-universit"at d"usseldorf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/rkward-devel/attachments/20110908/d4e13380/attachment.sig>