[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Perl bindings docstrings Re: svn commit: r1488693 - /subversion/trunk/subversion/bindings/swig/perl/native/Client.pm

From: Daniel Shahaf <danielsh_at_apache.org>
Date: Sun, 7 Jul 2013 17:33:15 +0000

On Sun, Jul 07, 2013 at 05:54:03PM +0200, Roderich Schupp wrote:
> On Sun, Jul 7, 2013 at 5:11 PM, Daniel Shahaf <danielsh_at_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
Received on 2013-07-07 19:33:27 CEST

This is an archived mail posted to the Subversion Dev mailing list.