From c62eb80c511d8a0daab74bb71d7f5f3573a5d07a Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Tue, 16 Jan 2007 02:06:26 +0000
Subject: [PATCH] Document muscat to meet the new doc style

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@227345 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/muscat/functions/muscat-close.xml   | 49 +++++++++++++--
 reference/muscat/functions/muscat-get.xml     | 46 ++++++++++++--
 reference/muscat/functions/muscat-give.xml    | 54 +++++++++++++++--
 .../muscat/functions/muscat-setup-net.xml     | 59 ++++++++++++++----
 reference/muscat/functions/muscat-setup.xml   | 60 +++++++++++++++----
 reference/muscat/reference.xml                |  8 ++-
 6 files changed, 241 insertions(+), 35 deletions(-)

diff --git a/reference/muscat/functions/muscat-close.xml b/reference/muscat/functions/muscat-close.xml
index 571a5ff2ed..2c938682e3 100644
--- a/reference/muscat/functions/muscat-close.xml
+++ b/reference/muscat/functions/muscat-close.xml
@@ -1,19 +1,58 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <refentry id="function.muscat-close">
  <refnamediv>
   <refname>muscat_close</refname>
-  <refpurpose>Shuts down the muscat session and releases any memory back to PHP</refpurpose>
+  <refpurpose>Shuts down the muscat session</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>void</type><methodname>muscat_close</methodname>
    <methodparam><type>resource</type><parameter>muscat_handle</parameter></methodparam>
   </methodsynopsis>
   &warn.experimental.func;
-  &warn.undocumented.func;
+  <para>
+   Shuts down the muscat session and releases any memory back to PHP.
+  </para>
  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>muscat_handle</parameter></term>
+     <listitem>
+      <para>
+       A muscat session handler, returned by 
+       <function>muscat_setup</function> or 
+       <function>muscat_setup_net</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>muscat_setup</function></member>
+    <member><function>muscat_setup_net</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/muscat/functions/muscat-get.xml b/reference/muscat/functions/muscat-get.xml
index 694c7b3c43..c9613f2239 100644
--- a/reference/muscat/functions/muscat-get.xml
+++ b/reference/muscat/functions/muscat-get.xml
@@ -1,20 +1,58 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <refentry id="function.muscat-get">
  <refnamediv>
   <refname>muscat_get</refname>
   <refpurpose>Gets a line back from the core muscat API</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>muscat_get</methodname>
    <methodparam><type>resource</type><parameter>muscat_handle</parameter></methodparam>
   </methodsynopsis>
   &warn.experimental.func;
-  &warn.undocumented.func;
+  <para>
+   Gets a line back from the core muscat API.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>muscat_handle</parameter></term>
+     <listitem>
+      <para>
+       A muscat session handler, returned by 
+       <function>muscat_setup</function> or 
+       <function>muscat_setup_net</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the muscat response, as a string.
+  </para>
   &return.falseproblem;
  </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>muscat_give</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/muscat/functions/muscat-give.xml b/reference/muscat/functions/muscat-give.xml
index 360f923c57..63573db195 100644
--- a/reference/muscat/functions/muscat-give.xml
+++ b/reference/muscat/functions/muscat-give.xml
@@ -1,20 +1,66 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
 <refentry id="function.muscat-give">
  <refnamediv>
   <refname>muscat_give</refname>
   <refpurpose>Sends string to the core muscat API</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>void</type><methodname>muscat_give</methodname>
    <methodparam><type>resource</type><parameter>muscat_handle</parameter></methodparam>
    <methodparam><type>string</type><parameter>string</parameter></methodparam>
   </methodsynopsis>
   &warn.experimental.func;
-  &warn.undocumented.func;
+  <para>
+   Sends a <parameter>string</parameter> to the core muscat API.  
+  </para>
  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>muscat_handle</parameter></term>
+     <listitem>
+      <para>
+       A muscat session handler, returned by 
+       <function>muscat_setup</function> or 
+       <function>muscat_setup_net</function>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>string</parameter></term>
+     <listitem>
+      <para>
+       The string to be sent
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>muscat_get</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/muscat/functions/muscat-setup-net.xml b/reference/muscat/functions/muscat-setup-net.xml
index 83b55106ab..77ad164cd2 100644
--- a/reference/muscat/functions/muscat-setup-net.xml
+++ b/reference/muscat/functions/muscat-setup-net.xml
@@ -1,26 +1,65 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <refentry id="function.muscat-setup-net">
  <refnamediv>
   <refname>muscat_setup_net</refname>
-  <refpurpose>Creates a new muscat session and returns the handle</refpurpose>
+  <refpurpose>Creates a new muscat session</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>resource</type><methodname>muscat_setup_net</methodname>
    <methodparam><type>string</type><parameter>muscat_host</parameter></methodparam>
+   <methodparam><type>int</type><parameter>port</parameter></methodparam>
   </methodsynopsis>
   &warn.experimental.func;
   <para>
-   <function>muscat_setup_net</function> creates a new muscat session and
-   returns the handle.
-  </para>
-  <para>
-   <parameter>muscat_host</parameter> is the hostname to connect to.
-   <parameter>port</parameter> is the port number to connect to.
+   Creates a new muscat session.
   </para>
  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>muscat_host</parameter></term>
+     <listitem>
+      <para>
+       The host name to connect to
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>port</parameter></term>
+     <listitem>
+      <para>
+       The port number to connect to
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns a session handler or &false; on error.
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>muscat_setup</function></member>
+    <member><function>muscat_close</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/muscat/functions/muscat-setup.xml b/reference/muscat/functions/muscat-setup.xml
index 66d17210e0..eec9e1e081 100644
--- a/reference/muscat/functions/muscat-setup.xml
+++ b/reference/muscat/functions/muscat-setup.xml
@@ -1,12 +1,13 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <refentry id="function.muscat-setup">
  <refnamediv>
   <refname>muscat_setup</refname>
-  <refpurpose>Creates a new muscat session and returns the handle</refpurpose>
+  <refpurpose>Creates a new local muscat session</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>resource</type><methodname>muscat_setup</methodname>
    <methodparam><type>int</type><parameter>size</parameter></methodparam>
@@ -14,15 +15,52 @@
   </methodsynopsis>
   &warn.experimental.func;
   <para>
-   &warn.undocumented.func;
-  </para>
-  <para>
-   <parameter>size</parameter> is the amount of memory in bytes to allocate
-   for muscat. <parameter>muscat_dir</parameter> is the muscat installation
-   dir e.g. "/usr/local/empower", it defaults to the compile time muscat
-   directory.
+   Creates a new local muscat session.
   </para>
  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>size</parameter></term>
+     <listitem>
+      <para>
+       The amount of memory in bytes to allocate for muscat
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>muscat_dir</parameter></term>
+     <listitem>
+      <para>
+       The muscat installation dir e.g. "/usr/local/empower", it defaults to
+       the compile time muscat directory.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns a session handler or &false; on error.
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>muscat_setup_net</function></member>
+    <member><function>muscat_close</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+ 
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/muscat/reference.xml b/reference/muscat/reference.xml
index 5bce927e32..b38bc485f1 100644
--- a/reference/muscat/reference.xml
+++ b/reference/muscat/reference.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <!-- Purpose: basic.session -->
 <!-- Membership: pecl, external -->
 <!-- State: experimental -->
@@ -11,6 +11,12 @@
   <partintro>
    <section id="muscat.intro">
     &reftitle.intro;
+    <para>
+     This extension provides an interface to the Muscat 3.6 search system.
+     Muscat doesn't exist anymore, but the <ulink
+     url="&url.dom3.spec;">Xapian</ulink> project may provide you with a
+     good alternative.
+    </para>
     &warn.experimental;
    </section>