[rkward-devel] roxygen2 docs for rkward package

[meik michalke]

hi,

am Samstag 10 September 2011 (12:07) schrieb Thomas Friedrichsmeier:
> yes, fully agreed. I was looking into how "roxygenization" would be added
> to our maintainance scripts

roxygenize() only needs to be called if docs and/or namespace contents were 
changed; or let's say, whenever the actual docs would have changed, too. so 
this could be left to be done manually after changes, and then the updated Rd 
files can be committed via svn as well. otherwise roxygen2 would become a 
dependency, wouldn't it?

> things that made me wonder. One thing is that rk.record.plot-docs
> apparently got missing in the conversion (I hope these were the only
> ones).

yes, i think that's the one file i was referring to earlier. Rd2roxygen just 
didn't take it, i have no idea why. it would need manual translation once, but 
i didn't get to that yet.

> Another thing that I just noted is that the generated pages appear to lack
> a "usage" section, which is pretty confusing, esp. on pages listing
> multiple functions.

in contrast to roxygen, roxygen2 should create these sections automatically 
from the function definition. if that doesn't fit it can be forced by 
specifying @usage.

> Also there may be some more subtle issues. For instance, on the roxygenized
> variant of the rk.misc-page, the "Details" for rk.rename.in.container()
> have moved into the "Description"-section for the whole page.

roxygen2 uses a slightly different order of the first sections than roxygen, 
which is more intuitive: first paragraph becomes the title (can be overwritten 
by @title), the second a short description and everything after that goes to 
details. end of paragraphs are indicated by an empty "#'" line. so if you 
would like to have changes here, just change this order. does this help?


viele grüße :: m.eik

-- 
dipl. psych. meik michalke
institut f"ur experimentelle psychologie
abt. f"ur diagnostik und differentielle psychologie
heinrich-heine-universit"at d-40204 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/20110911/678ef785/attachment.sig>