[Xapian-discuss] Xapian-discuss Digest, Vol 88, Issue 9

[James Aylett]

Please keep replies on-list.

On 21 Sep 2011, at 15:19, Sam Millman wrote:

>> One of the problems we have is it's not always obvious where to look in the docs to find things out.
> 
> Absolutely. Like when I first saw the documentation I thought "I'll click on indexing to see how to index". But instead of talking about how to form a indexer it just talks about certain considerations you gotta take.

Yeah, we should probably push the overview & quickstart before you try to read anything else :)

>> The new value will replace any existing value with the same number (or if the new value is empty, it will remove any existing value with the same number).
> 
> That's exactly what is confusing me about that function. It says it requires a Xapian::valueno which I try to find out about but get bombarded by other confusing method descriptions before I have even learnt how to index fully.

Hmm. From our point of view, I'd say you're trying to run before you can walk: you're trying to add values before knowing how you're going to use them :)

There should probably be a "what values get used for" document to help here.

> Also what does it mean by number? How does number work? what does it do in Xapian? Do I need to manipulate it in anyway?

It's…a number. Like: an integer. It specifies *which* value in the document you're operating on. I think the problem here goes back to an earlier point: this is more obvious if you're a C++ programmer (because the typedef tells you that Xapian::valueno is unsigned), and we need to cater better for (in this case) PHP programmer.

It's possible that rewording the docstring here might help…the formal parameter name is supposed to be a hint that these are numbered slots to put values in. Maybe something like:

Set the Document value in the given slot.

The new value will replace any existing value in the same slot (or if the new value is empty, it will remove any existing value in the same slot).

It doesn't help that value has a dual meaning here because of the name of the formal parameter, but that's difficult to change :/

J

-- 
 James Aylett
 talktorex.co.uk - xapian.org - devfort.com