[Xapian-discuss] Understanding API Documentation for PHP

[Olly Betts]

On Wed, Sep 21, 2011 at 08:51:28AM +0100, James Aylett wrote:
> On 21 Sep 2011, at 00:23, Peter Van Dijk wrote:
> 
> > The PHP wrapper really doesn't clue you in as to what types you should be
> > passing to any given method, so you'll find yourself having to wrap a lot of
> > stuff with intval( ) or strval( ) for the methods to work correctly,
> > which is a side effect of trying to use a wrapper designed for a strongly
> > typed language with a loosely typed one.
> 
> I think this is because of a lack of attention to the PHP bindings,
> sadly;

No, that's not true.

> the aim is for idiomatic code in the bindings language to work,
> and we do well in say Python but less well in others.

Python has this issue too:

>>> import xapian
>>> doc = xapian.Document()
>>> doc.add_term(7)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: in method 'Document_add_term', argument 2 of type 'std::string const &'

As Peter says, it's really just that you're talking to a more strongly typed
language.

We could override this with some effort, but I'm not sure it's worthwhile -
typically you don't want to be passing a number as a term, so I think it's
more likely to hide bugs than help users.  It's easy to say "yes, I really
did want to do that".

But I'm surprised that Peter says "a lot" - perhaps there are cases where
we should be doing this.  Some concrete examples would be useful rather
than just talking in generalities.

Cheers,
    Olly