[GSoC-PortA] v1->v2 migration guide

[Ross Bennett]

On Sun, Aug 18, 2013 at 5:24 AM, Brian G. Peterson <brian at braverock.com>wrote:

> 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'll take a closer look at what else needs to be done so the _v1 and _v2
functions don't have to be exported for backwards compatibility. I think I
just need to change add.objective to accept a v1_constraint object.

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
>

Thank you for cleaning up the code documentation. I think I am clear on
everything you did and why now that I am seeing the code and the reference
manual.


>
> 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 agree that would be good to do as well. Before we start doing that, I
have a few thoughts on the chart functions. The plot function plots both
the scatter and weights charts. If the user just wants to chart the weights
or the scatter, they have to use chart.Weights.(DE, ROI, RP, etc.). I think
it would be nice if the user just had to call chart.Weights(object) or
chart.Scatter(object). Do you think this should be done?

The PerformanceAnalytics packages already has a chart.Scatter function.
Will we have any naming or masking issues if I make chart.Scatter a
function for the different optimize.portfolio.objects?


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

I completely agree. I'll send a separate email with thoughts on the outline
for the package intro building on the portfolio_vignette.


>
> 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
>
> _______________________________________________
> GSoC-PortA mailing list
> GSoC-PortA at lists.r-forge.r-project.org
> http://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/gsoc-porta
>
>
Thanks,
Ross
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.r-forge.r-project.org/pipermail/gsoc-porta/attachments/20130818/40f6e870/attachment.html>