From 72744c5695ebe62075228bda8f4f7468ef7eea19 Mon Sep 17 00:00:00 2001
From: Mehdi Achour <didou@php.net>
Date: Tue, 31 Aug 2004 01:20:59 +0000
Subject: [PATCH] imap_(g|s)et_acl is only available with c-client2000 or
 greater fix imap_bodystruct proto start documenting imap_thread # the second
 parameter, thread[XX.next] and thread['XX.branch'] needs to be documented

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@167678 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/imap/functions/imap-bodystruct.xml |  4 +-
 reference/imap/functions/imap-getacl.xml     |  9 ++--
 reference/imap/functions/imap-setacl.xml     |  8 ++-
 reference/imap/functions/imap-thread.xml     | 52 ++++++++++++++++++--
 4 files changed, 63 insertions(+), 10 deletions(-)

diff --git a/reference/imap/functions/imap-bodystruct.xml b/reference/imap/functions/imap-bodystruct.xml
index 3144234141..e8e80d633c 100644
--- a/reference/imap/functions/imap-bodystruct.xml
+++ b/reference/imap/functions/imap-bodystruct.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/imap.xml, last change in rev 1.58 -->
   <refentry id='function.imap-bodystruct'>
    <refnamediv>
@@ -14,7 +14,7 @@
       <type>object</type><methodname>imap_bodystruct</methodname>
       <methodparam><type>resource</type><parameter>stream_id</parameter></methodparam>
       <methodparam><type>int</type><parameter>msg_no</parameter></methodparam>
-      <methodparam><type>int</type><parameter>section</parameter></methodparam>
+      <methodparam><type>string</type><parameter>section</parameter></methodparam>
      </methodsynopsis>
     <para>
      &warn.undocumented.func;
diff --git a/reference/imap/functions/imap-getacl.xml b/reference/imap/functions/imap-getacl.xml
index 5d5c94cb8f..1aec2a9bc7 100644
--- a/reference/imap/functions/imap-getacl.xml
+++ b/reference/imap/functions/imap-getacl.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
   <refentry id="function.imap-getacl">
    <refnamediv>
     <refname>imap_getacl</refname>
@@ -16,9 +16,12 @@
     </methodsynopsis>
 
      &warn.undocumented.func;
-
     <para>
-     See also: <function>imap_setacl</function>.
+     This function is currently only available to users of the c-client2000
+     or greater library.
+    </para>             
+    <para>
+     See also <function>imap_setacl</function>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/imap/functions/imap-setacl.xml b/reference/imap/functions/imap-setacl.xml
index 7d4b905bc3..6be200cf15 100644
--- a/reference/imap/functions/imap-setacl.xml
+++ b/reference/imap/functions/imap-setacl.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
 <!-- splitted from ./en/functions/imap.xml, last change in rev 1.58 -->
   <refentry id='function.imap-setacl'>
    <refnamediv>
@@ -21,7 +21,11 @@
      &warn.undocumented.func;
     </para>
     <para>
-     See also: <function>imap_getacl</function>.
+     This function is currently only available to users of the c-client2000
+     or greater library.
+    </para>
+    <para>
+     See also <function>imap_getacl</function>.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/imap/functions/imap-thread.xml b/reference/imap/functions/imap-thread.xml
index 69376c25e5..4b3a758487 100644
--- a/reference/imap/functions/imap-thread.xml
+++ b/reference/imap/functions/imap-thread.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/imap.xml, last change in rev 1.58 -->
   <refentry id='function.imap-thread'>
    <refnamediv>
     <refname>imap_thread</refname>
     <refpurpose>
-     Return threaded by REFERENCES tree
+     Returns a tree of threaded message
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -16,7 +16,53 @@
       <methodparam choice="opt"><type>int</type><parameter>options</parameter></methodparam>
      </methodsynopsis>
     <para>
-     &warn.undocumented.func;
+     <function>imap_thread</function> returns an associative array containing
+     a tree of messages threaded by <literal>REFERENCES</literal>, or &false;
+     on error.
+    </para>
+    <para>
+     Every message in the current mailbox will be represented by three entries
+     in the resulting array:
+     <itemizedlist>
+      <listitem>
+       <varname>$thread["XX.num"]</varname> - current message number
+      </listitem>
+      <listitem>
+       <varname>$thread["XX.next"]</varname>
+      </listitem>
+      <listitem>
+       <varname>$thread["XX.branch"]</varname> 
+      </listitem>
+     </itemizedlist>
+    </para>
+    <para>
+     <example>
+      <title><function>imap_thread</function> Example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+
+// Here we're outputting the threads of a newsgroup, in HTML
+
+$nntp = imap_open('{news.example.com:119/nntp}some.newsgroup', '', '');
+$threads = imap_thread($nntp);
+
+foreach ($thread as $key => $val) {
+  $tree = explode('.', $key);
+  if ($tree[1] == 'num') {
+    $header = imap_headerinfo($nntp, $val);
+    echo "<ul>\n\t<li>" . $header->fromaddress . "\n";
+  } elseif ($tree[1] == 'branch') {
+    echo "\t</li>\n</ul>\n";
+  }
+}
+
+imap_close($nntp);
+
+?>
+]]>
+      </programlisting>
+     </example>
     </para>
    </refsect1>
   </refentry>