Document the SearchResult facility.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@199866 c90b9560-bf6c-de11-be94-00142212c4b1

reference/yaz/functions/yaz-hits.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <refentry id="function.yaz-hits">
  <refnamediv>
   <refname>yaz_hits</refname>
@@ -10,10 +10,11 @@
   <methodsynopsis>
    <type>int</type><methodname>yaz_hits</methodname>
    <methodparam><type>resource</type><parameter>id</parameter></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>searchresult</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>yaz_hits</function> returns the number of hits for the last
-   search.
+   search. 
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -28,6 +29,14 @@
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term><parameter>searchresult</parameter></term>
+     <listitem>
+      <para>
+       Result array for detailed search result information.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -37,6 +46,62 @@
    Returns the number of hits for the last search or 0 if no search was 
    performed.
   </para>
+  <para>
+   The search result array (if supplied) holds information that
+   is returned by a Z39.50 server in the SearchResult-1
+   format part of a search response.
+   The SearchResult-1 format can be used to obtain information
+   about hit counts for various parts of the query (subquery).
+   In particular, it is possible to obtain hit counts for the individual
+   search terms in a query. Information for first
+   subquery is in $array[0], second subquery in $array[1], and so forth.
+  </para>
+  <table>
+   <title>searchresult members</title>
+   <tgroup cols="2">
+    <colspec colwidth="1*" colname="element"/>
+    <colspec colwidth="2*" colname="description"/>
+    <thead>
+     <row>
+      <entry>Element</entry>
+      <entry>Description</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry><literal>id</literal></entry>
+      <entry>Sub query ID2 (string)</entry>
+     </row>
+     <row>
+      <entry><literal>count</literal></entry>
+      <entry>Result count / hits (integer)</entry>
+     </row>
+     <row>
+      <entry><literal>subquery.term</literal></entry>
+      <entry>Sub query term (string)</entry>
+     </row>
+     <row>
+      <entry><literal>interpretation.term</literal></entry>
+      <entry>Interpretated sub query term (string)</entry>
+     </row>
+     <row>
+      <entry><literal>recommendation.term</literal></entry>
+      <entry>Recommended sub query term (string)</entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </table>     
+  <note>
+   <para>
+    The SearchResult facility requires PECL YAZ 1.0.5
+    or later and YAZ 2.1.9 or later.
+   </para>
+  </note>
+  <note>
+   <para>
+    Very few Z39.50 implementations support the SearchResult facility.
+   </para>
+  </note>
  </refsect1>
 </refentry>