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

On Mon, Jul 8, 2013 at 5:32 PM, Ben Reser <ben_at_reser.org> wrote:

> > So it's as simple as "extract docstring from C header and reformat as
> POD".
>

Actually I meant "So it's NOT as simple...", at least if you want to fully
automate this.

> Exactly this. We need this documentation. Sometimes we're behind on
> producing it, but once produced it's rarely ever wrong. There is no
> way for a Perl user to know how we've wrapped things from the C API.
>

+1

> So in short, suggesting that we remove this documentation or produce
> it in some automated way is probably going to produce far worse
> results.
>

+1

I looked at the Perl bindings for Gtk+ and it seems that they generate only
the simple doc stuff (i.e. method signature and list of parameters and
their types),
while any textual description is by hand (though may have been
culled intially from the C level docs). Anyway, they're in better position
to do this,
since they don't use Swig, but generate XS themselves. Hence they already
"know" how types and signatures are mapped, while for Subversion this
is only known to Swig.

> Unless someone has invented real AI I just don't see how you can automate
> this.

But certainly one could whip up a simple Perl script (oder editor macros) to
spare us from the tedium of manually copying and pasting the C doc comments,
remove the leading * on each line, turn "@a foo" into "C<$foo>" etc.

Cheers, Roderich
Received on 2013-07-09 09:19:29 CEST