Document query fragments

First version, please review.

I tried to add anything special I could remember abour our queries.

+  // MIN() does not have a useful meaning except that it helps to correctly
+  // aggregate the thread on PostgreSQL.
   $fragments['select'][]      = 'MIN(pm.subject) as subject';

Except it sort of does - in privatemsg 5.x, each message could have a separate subject, and technically this can also be achieved in privatemsg 6.x too. a common prefix for replies is "Re: ". since R is more than half way through the alphabet, MIN works correctly a majority of the time to get the "correct" thread subject.

+  // Select number of messages in the thread if enabled.

"Select number of messages in the thread if the count is set to be displayed." ?

+  // Only count new *and* undeleted messages of that user.

"Only count new messages that have not been deleted" ?

+ * @param $names
+ *   Which names are already part of the existing search string and should be excluded.

I don't think we should list the rationale here for why they are excluded - others may wish to use the query for other reasons? so simple "A list of names to be excluded from the matches" or something like that may be better.

+  // The lowest value is higher than 0 if all recipients have deleted a message·

mistaken character at the end?

Except it sort of does - in privatemsg 5.x, each message could have a separate subject, and technically this can also be achieved in privatemsg 6.x too. a common prefix for replies is "Re: ". since R is more than half way through the alphabet, MIN works correctly a majority of the time to get the "correct" thread subject.

Yeah, except I do not count "most of the time, it does what we expect" as a useful meaning :) And that is only true for english. For example, the german tranlation of "RE:" is "AW:". And A is pretty much the first character we have :)

I don't think we should list the rationale here for why they are excluded - others may wish to use the query for other reasons? so simple "A list of names to be excluded from the matches" or something like that may be better.

Yep, makes sense. I've seen you are already doing that in the filter_autocomplete query but I forgot to change this.

Updated, I also forgot to add the changes in privatemsg_filter.module.

Documentation looks good.

Commited to 6.x-1.x-dev. There are so many changes in that area in D7 that it does not make much sense to port this to D7, so setting to fixed.