Search hook docs?

Is there an easier way to learn how to create a search hook
than to check how it was done in the comments or the xarbb
modules?
Is there any documentation on this topic?
- what vars are supplied as argument, what's their format
- what's the expected return value of the search hits,
should my function create urls and if not, where are the urls built,...
- ...