From a5bb3ee60579af441b257cdff818434d54a0f4b0 Mon Sep 17 00:00:00 2001
From: Friedhelm Betz <betz@php.net>
Date: Fri, 8 Jul 2005 18:12:55 +0000
Subject: [PATCH] new docstyle, more about return values, see also
 session_regenerate_id

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@190288 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/session/functions/session-id.xml | 80 +++++++++++++++-------
 1 file changed, 56 insertions(+), 24 deletions(-)

diff --git a/reference/session/functions/session-id.xml b/reference/session/functions/session-id.xml
index 9091163b33..22da964fe8 100644
--- a/reference/session/functions/session-id.xml
+++ b/reference/session/functions/session-id.xml
@@ -1,37 +1,21 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!-- splitted from ./en/functions/session.xml, last change in rev 1.2 -->
 <refentry id="function.session-id">
  <refnamediv>
   <refname>session_id</refname>
   <refpurpose>Get and/or set the current session id</refpurpose>
  </refnamediv>
- <refsect1>
-  <title>Description</title>
+ <refsect1 role="description">
+  &reftitle.description;
   <methodsynopsis>
    <type>string</type><methodname>session_id</methodname>
    <methodparam choice="opt"><type>string</type><parameter>id</parameter></methodparam>
   </methodsynopsis>
   <para>
-   <function>session_id</function> returns the session id for the current
-   session.
+   <function>session_id</function> is used to get or set the session id for
+   the current session.
   </para>
-  <para>
-   If <parameter>id</parameter> is specified, it will replace the current
-   session id. <function>session_id</function> needs to be called before
-   <function>session_start</function> for that purpose. Depending on the
-   session handler, not all characters are allowed within the session id.
-   For example, the file session handler only allows characters in the range
-   <literal>a-z, A-Z and 0-9</literal>!
-  </para>
-  <note>
-   <simpara>
-    When using session cookies, specifying an <parameter>id</parameter> for
-    <function>session_id</function> will always send a new cookie when
-    <function>session_start</function> is called, regardless if the current
-    session id is identical to the one being set.
-   </simpara>
-  </note>
   <para>
    The constant <systemitem>SID</systemitem> can also be used to
    retrieve the current name and session id as a string suitable for
@@ -39,14 +23,62 @@
    the client didn't send the right cookie. See also <link
    linkend="ref.session">Session handling</link>.
   </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
   <para>
-   See also <function>session_start</function>,
-   <function>session_set_save_handler</function>, and
-   <link linkend="ini.session.save-handler">session.save_handler</link>.
+   <variablelist>
+    <varlistentry>
+     <term><parameter>id</parameter></term>
+      <listitem>
+       <para>
+        If <parameter>id</parameter> is specified, it will replace the current
+        session id. <function>session_id</function> needs to be called before
+        <function>session_start</function> for that purpose. Depending on the
+        session handler, not all characters are allowed within the session id.
+        For example, the file session handler only allows characters in the
+        range <literal>a-z, A-Z and 0-9</literal>!
+       </para>
+       <note>
+        <simpara>
+         When using session cookies, specifying an <parameter>id</parameter>
+         for <function>session_id</function> will always send a new cookie
+         when <function>session_start</function> is called, regardless if the
+         current session id is identical to the one being set.
+        </simpara>
+       </note>
+      </listitem>
+     </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   <function>session_id</function> returns the session id for the current
+   session or the empty string (<literal>""</literal>) if there is no current
+   session (no current session id exists).
+  </para>
+ </refsect1>
+
+<refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>session_regenerate_id</function></member>
+    <member><function>session_start</function></member>
+    <member><function>session_set_save_handler</function></member>
+    <member>
+     <link linkend="ini.session.save-handler">session.save_handler</link>
+    </member>
+   </simplelist>
   </para>
  </refsect1>
 </refentry>
 
+
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml