On Sun, Jul 07, 2013 at 05:54:03PM +0200, Roderich Schupp wrote:
> On Sun, Jul 7, 2013 at 5:11 PM, Daniel Shahaf <danie...@apache.org> wrote:
>
> > Nothing is useful without proper documentation, but devil's advocate
> > says the bindings can be quite usable if you document only the delta
> > between SVN::Client->info42 and svn_client_info42().
> >
>
> First of all, you have to tell people that there is a SVN::Client->info42
> at all.
> The current POD only talks about SVN::Client->info, you have to look
> into the SVN::Client (Perl) source to see that info42 is in the @all_fn
> list,
> so it's probably wrapped (of course, this could also just be a typo).
> So that't the reason for the ADDITIONAL METHODS section.
>
> As for the "delta" (Perl vs C) argument: all Perl etc bindings for large
> C-based libraries have this problem. With my Perl developer hat on
> I would probably scoff at your suggestion - if I want to hack Subversion
> in Perl why should I be forced to look at C documentation?
>
Yes it would be useful to have documents in pod/perldoc format, but how
do we maintain them?
If a change is made to the docstring of a released API (yes, this should
be rare, but it's not unheard of: svn_client_relocate, svn_client_blame5),
how do we ensure that the docstring of the wrapped API gets the same change?
Is it really the best use of volunteer time to manually maintain a copy
of all our docstrings?
% wc subversion/include/*.h | tail -n1
43515 205066 1587361 total
Or perhaps we should look into a way to generate
the Perl bindings' docstrings from the C API docstrings?
> Cheers, Roderich
