Clarify purpose of options parameter, be more explicit about return values; extra example; miscellaneous tidy ups.

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

reference/filesystem/functions/pathinfo.xml

@@ -14,8 +14,9 @@
    <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>PATHINFO_DIRNAME | PATHINFO_BASENAME | PATHINFO_EXTENSION | PATHINFO_FILENAME</initializer></methodparam>
   </methodsynopsis>
   <para>
-   <function>pathinfo</function> returns an associative array
-   containing information about <parameter>path</parameter>.
+   <function>pathinfo</function> returns information about
+   <parameter>path</parameter>: either an associative array or a string,
+   depending on <parameter>options</parameter>.
   </para>
  </refsect1>
 
@@ -27,7 +28,7 @@
      <term><parameter>path</parameter></term>
      <listitem>
       <para>
-       The path being checked.
+       The path to be parsed.
       </para>
      </listitem>
     </varlistentry>
@@ -35,13 +36,14 @@
      <term><parameter>options</parameter></term>
      <listitem>
       <para>
-       You can specify which elements are returned with optional parameter
-       <parameter>options</parameter>. It composes from
+       If present, specifies a specific element to be returned; one of
        <constant>PATHINFO_DIRNAME</constant>,
        <constant>PATHINFO_BASENAME</constant>,
-       <constant>PATHINFO_EXTENSION</constant> and
-       <constant>PATHINFO_FILENAME</constant>. It
-       defaults to return all elements.
+       <constant>PATHINFO_EXTENSION</constant> or
+       <constant>PATHINFO_FILENAME</constant>.
+      </para>
+      <para>If <parameter>options</parameter> is not specified, returns all
+       available elements.
       </para>
      </listitem>
     </varlistentry>
@@ -52,13 +54,22 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   The following associative <type>array</type> elements are returned:
+   If the <parameter>options</parameter> parameter is not passed, an
+   associative <type>array</type> containing the following elements is
+   returned:
    <literal>dirname</literal>, <literal>basename</literal>,
    <literal>extension</literal> (if any), and <literal>filename</literal>.
   </para>
+  <note>
+   <para>
+    If the <parameter>path</parameter> does not have an extension, no
+    <literal>extension</literal> element will be returned
+    (see second example below).
+   </para>
+  </note>
   <para>
-   If <parameter>options</parameter> is used, this function will return a 
-   <type>string</type> if not all elements are requested.
+   If <parameter>options</parameter> is present, returns a 
+   <type>string</type> containing the requested element.
   </para>
  </refsect1>
 
@@ -110,6 +121,30 @@ echo $path_parts['filename'], "\n"; // since PHP 5.2.0
 lib.inc.php
 php
 lib.inc
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title><function>pathinfo</function> example showing difference between null and no extension</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$path_parts = pathinfo('/path/nullextension.');
+var_dump($path_parts['extension']);
+
+$path_parts = pathinfo('/path/noextension');
+var_dump($path_parts['extension']);
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+string(0) ""
+
+Notice:  Undefined index:  extension in /test.php on line 6
 ]]>
     </screen>
    </example>
@@ -127,8 +162,8 @@ lib.inc
   </note>
   <note>
    <para>
-    <function>pathinfo</function> is locale aware, so for it to parse the path 
-    correctly with multibyte character, the matching locale must be set using 
+    <function>pathinfo</function> is locale aware, so for it to parse a path 
+    containing multibyte characters correctly, the matching locale must be set using 
     the <function>setlocale</function> function.
    </para>
   </note>