[Xapian-discuss] Perl XS bindings, postlist_begin

[Olly Betts]

On Sat, May 29, 2004 at 09:53:28AM +0100, Francis Irving wrote:
> On Fri, May 28, 2004 at 03:16:10PM +0100, Olly Betts wrote:
> > On Fri, May 28, 2004 at 02:59:51PM +0100, Francis Irving wrote:
> > > Something bad is happening, but I don't quite understand why.
> > > Exception: Db block overwritten at ./index.pl line 68, <F> line 2002.
> > 
> > [...]
> > That error message ought to be reworded to explain better what's
> > actually happened and point to reopen().
> 
> Ah, I hadn't realised what a "batch" of changes is.  I'd assumed that
> a batch was until a WritableDatabase objects was destroyed, but it
> seems to happen more often than that.

You can flush batched up changes explicitly by calling flush().  And
a database will automatically flush itself periodically, and on certain
operations (for example, if you try to modify a document that you've
only just added, the database currently forces a flush to avoid special
case code for an unusual corner case - at least some of these forced
flushes probably should be removed, get_avlength() being the first
target).

> Also, I haven't delved into the use of set_error_handler in PHP 4.
> There are no exceptions yet, so errors which aren't return codes are
> awkward to handle.

We've discussed this before, and longer term we'll probably move to an
error code strategy for the library, with in-lined wrappers which
convert these to exceptions for developers who prefer an exception
error model.  You could think of this as offering C++-with-exceptions
bindings to a C++-without-exceptions library.

This would benefit the bindings - currently every method has a try/catch
wrapper to convert exceptions into something the language supports
(unhelpfully, this is an error in the case of PHP4).  It would also allow
shared libraries on platforms which have problems with exceptions being
thrown from shared libraries (Solaris with GCC is one example).

For now, I guess we can only choose which exceptions are non-fatal and
catch and convert those to error codes in languages like PHP4.  The
awkward part is that it isn't currently clearly defined which methods
can throw which exceptions.

> Just had a thought... One way to improve documentation without much
> effort would be to have user comments on the online docs, like the PHP
> and MySQL websites.  If each Xapian function was separately
> commentable website, then people using it would add explanations and
> suggestions.
> 
> This would be both directly helpful, and the material could be
> returned back into the documentation proper and the comments removed.
> Easier than allocating separate time to documentation writing, and
> trying to second guess what people want to know.
> 
> Instead of comments, a Wiki could do this as well - and I mean a wiki
> where people edit the documentation itself, not one with no initial
> framework.

I'd wondered about something like this.  The benefit of a Wiki (and
to a lesser extent of a comments section) is that it's very immediate -
you can fix that typo, or clarify that confusing wording without having
to check the file out of CVS, change it, generate a patch, mail it in,
and hope it gets acted on (some projects seem to be patch blackholes).

But the downside is that the comments often seem to be confused, just
plain wrong, or questions (usually without corresponding answers).  I've
rarely found the comments on the PHP docs useful, for example.

Perhaps what's needed is a regular sweep through the wiki/comments to
collect up useful additions and merge them into the documents, and
to any incorrect information.

I'm also not sure what the best way is to work changes back in.  The
API docs are produced from the source code using doxygen to collate
special documentation comments.  We wouldn't really want to force
people to edit the source code comments, but edits to the generated
documentation are harder to patch back.

Perhaps we should just put up a wiki, preloaded with the documentation,
and see how it develops.  Can anyone suggest a suitable wiki?  One with
good support for change management would be good I guess...

Cheers,
    Olly