[Xapian-devel] Documentation for the PHP OO wrapper

[Olly Betts]

On Wed, May 10, 2006 at 12:08:45PM +0200, Daniel M?nard wrote:
> >Another way to approach it might be to postprocess Doxygen's XML output
> >(which would allow mechanical changes to match PHP syntax).
>
> I wrote an xslt script to test the idea (It is one of the first I write, 
> so there are surely a lot of "bad things" in it, don't hesitate to point 
> them !).

I don't know xslt, so I can't comment on that really.

> It produces a all-in-one html file (331Kb) :
> http://www.bdsp.tm.fr/aed/xapian/wrapperDoc/index.html

It looks pretty good.  I suspect __construct should probably be
described as "new <CLASSNAME>" since that's how the user will call it.

> I'm not very happy with the result because I had to hard code some 
> Xapian names in the xslt file, which was not what I wanted (maintenance 
> issue).

I think it's inevitably going to be somewhat inelegant because the
process of mapping the names has a number of special cases.  It should
be easier to maintain a mapping that to try to maintain parallel PHP
docs by hand - that's likely to result in more errors.  But it's a
problem that we're trying to duplicate knowledge contained in the SWIG
xapian.i and php/util.i files, as well as in SWIG itself to some extent.

> Generating a better doc require that the xslt file "knows" more about 
> what is specific to the wrapper but adding more and more tests and 
> conditions in the xslt file is probably not an option.

If it helps, we could generate a list of which classes and methods get
wrapped pretty easily I think.

Or perhaps we should approach this a different way and try to insert
this documentation into the generated PHP wrapper using SWIG magic (SWIG
can already add python docstrings for example).

If there a "PHP documentation comment" convention, we can use that.
Otherwise doxygen supports PHP "to some extent" apparently.

> I miss time for now to go on, and I am not sure this is the way to go : 
> maintenance of this xml file is probably a problem...

Perhaps, but it was definitely an instructive experiment even if the
conclusion might end up being that it's not the way to go.  So thanks
for trying it.

> On the other hand, the method used to generate the doc for the PHP 
> wrapper can probably be re-used to generate specific doc for the other 
> bindings. So a generic solution would be better. An xml version of 
> xapian.i ?

I would certainly be good to sort this out for all languages the same
way.

> PS : by working on this, I found some errors which can perhaps be 
> corrected in the sources :
> - MSetIterator::get_document documents an "it" parameter which does not 
> exist

Fixed.

> - some methods arguments are not documented and don't have a name in 
> doxygen output (search for '$arg' in the html file)

I had a quick look and I think most of these are cases where the
method is defined inline in the header and the parameter is unused.
We could perhaps include the parameter name and then use a cast
to void or self-assignment to suppress the "unused parameter" error.

I'll have a look...

> - some methods of the wrapper can not be used from PHP 
> (Enquire:register_match_decider for example)

SWIG/PHP doesn't currently support directors (i.e. you the ability to
subclass a wrapped C++ class and then pass an instance of that to a
wrapped C++ function/method which can then call virtual methods
implemented in PHP) so MatchDecider isn't usable from PHP currently.

I suspect it's probably not that hard to implement - if someone can
sketch out what the code would look like for an example, I can
easily sort out generating it.  Otherwise I think I'll try to
finish merging the PHP5 wrapper generation into SWIG first (they've
kindly given me commit access so this should happen fairly soon).

Cheers,
    Olly