[GSoC-PortA] v1->v2 migration guide

[Brian G. Peterson]

On 08/18/2013 12:53 AM, Ross Bennett wrote:
>     I think we'll also want to consider collapsing some of the v1/v2
>     functions into the documentation for the main functions e.g.
>     contraint, objective, etc.  This can be done with the @rdname tag as
>     a single line comment before the v1/v2 functions, and then we can
>     put the text and all the @param and other tags in front of the main
>     wrapper function.
>
>
> I'm not entirely clear on this step. Take for example the add.objective
> functions. We have add.objective_v1.Rd, add.objective_v2.Rd, and
> add.objective.Rd files.
>
> add.objective_v2 has an @rdname and @alias tag
>
> add.objective is just the alias for add.objective_v2 and only has an
> @export tag.
>
> Are you saying the @param and other tags should go in front of the alias
> function?
>
> Should we keep _v1 documentation and export those functions for
> backwards compatibility.
>
> Can I just delete the _v2.Rd files in the man directory so we only have
> the _v1.Rd files and the unversioned Rd files?


Sorry if my instructions weren't particularly clear.

I was advocating for having only one documentation entry for e.g. 
add.constraint with add.constraint_v1 and add.constraint_v2 pointing to 
the main entry (so they'll be in the index, but not in the TOC).  This 
requires @rdname, @aliases, and occasionally @name tags on all the 
functions that you want to share a single entry.  We can't simply delete 
files we don't want, as they'll get recreated every time roxygenize is 
called.

I think it's fine to have both the _v1 and _v2 functions exported to the 
NAMESPACE (although not actually necessary if we trap and correct any 
old-style code).  I was suggesting that we combine the documentation, so 
that as we add more text, it goes in only one place.

I've taken a look at the code right now and tried to clean it up a bit 
while I assume all of you west coast folks are still asleep.

The new version of the pdf is attached, and my changes are contained in 
svn r2816

I think we should look closely at the descriptive text and parameters 
for the print, summary, plot, chart, extractStats,  etc. functions and 
see if we want to collapse their documentation too.

I think a package intro for the start of the PDF should be pretty high 
on the list.  with almost 80 pages of documentation, it's not fair to 
the user to dump them into add.constraint as their first stop.

Ross, I should be available all day today by phone or IM if any of the 
changes I made to the .R roxygen comments and the knock-on compiled .Rd 
files aren't clear.

Regards,

Brian

-- 
Brian G. Peterson
http://braverock.com/brian/
Ph: 773-459-4973
IM: bgpbraverock
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PortfolioAnalytics.pdf
Type: application/pdf
Size: 227783 bytes
Desc: not available
URL: <http://lists.r-forge.r-project.org/pipermail/gsoc-porta/attachments/20130818/53ba6d05/attachment-0001.pdf>