[rkward-devel] roxygen2 docs for rkward package

[Thomas Friedrichsmeier]

Hi,

On Sunday 11 September 2011, meik michalke wrote:
> 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?

only for the release manager(s). To be more specific, I intend to add this to 
make_dist.sh (probably as a separate script, though). That's the script I use 
for rolling the release .tar.gz from an SVN checkout. This already includes 
some of those steps which should have been done manually, already, but are 
easily forgotten, such as updating message catalogs, and in fact also 
roxygenization of the rkwardtests package.
 
> in contrast to roxygen, roxygen2 should create these sections automatically
> from the function definition.

Yes, but at least for me, it currently doesn't create a usage-section at all 
for more pages. I believe the reason is roxygen does not realize that these 
pages are about multiple functions. So I guess, we will need to do some more 
manual editing (splitting the docs in the sources, and using @rdname) to 
achieve correct results. I simply did not have time to play with that, yet, 
and I was sort of hoping, you had some totally simple and neat automatic 
solution up your sleeves.

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

Well, yes, but again, it means we will have to do some more manual editing, 
before we can let roxygen generate the docs for the rkward package. Thus, I'll 
exclude that from the roxygenization script, for now.

Regards
Thomas
-------------- 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/20110912/c1ff0e31/attachment.sig>