From 244993c7752eaedbb187b00aca6baa2b6ae28bbf Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Sun, 29 Sep 2002 03:39:23 +0000
Subject: [PATCH] Moving section on "How to read a function definition" here
 from tutorial.xml

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@97337 c90b9560-bf6c-de11-be94-00142212c4b1
---
 appendices/about.xml | 129 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 128 insertions(+), 1 deletion(-)

diff --git a/appendices/about.xml b/appendices/about.xml
index 77df04986e..73f50fa278 100644
--- a/appendices/about.xml
+++ b/appendices/about.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.16 $ -->
+<!-- $Revision: 1.17 $ -->
 
 <!--
   TODO: add manual conventions section (eg. how to read
@@ -111,6 +111,133 @@
    </para>
   </note>
  </sect1>
+
+ <sect1 id="about.prototypes">
+   <title>How to read a function definition (prototype)</title>
+   <para>
+    Each function is documented for quick reference, knowing how 
+    to read and understand the manual will make using PHP 
+    much easier.  Rather than relying on examples or cut/paste, you want 
+    to know how to read function definitions (prototypes).  Let's begin:
+   </para>
+   <note>
+    <title>
+     Prerequisite: Basic understanding of <link linkend="language.types">types</link>
+    </title>
+    <para>
+     Although PHP is a loosly typed language, it's important to have 
+     a basic understanding of <link linkend="language.types">types</link> as 
+     they have important meaning.
+    </para>
+   </note>
+   <para>
+    Function definitions tell us what 
+    type of value is <link linkend="functions.returning-values">returned</link>, 
+    let's use the definition for <function>strlen</function> as our first example:
+   </para>
+   <para>
+    <screen role="html">
+strlen
+
+(PHP 3, PHP 4 >= 4.0.0)
+strlen -- Get string length
+
+Description
+int strlen ( string str )
+
+Returns the length of string.
+    </screen>
+   </para>
+   <para>
+    <table>
+     <title>Explanation of a function definition</title>
+      <tgroup cols="2">
+       <thead>
+        <row>
+         <entry>Part</entry>
+         <entry>Description</entry>
+        </row>
+       </thead>
+       <tbody>
+        <row>
+         <entry>
+          strlen
+         </entry>
+         <entry>
+          The function name.
+         </entry>
+        </row>
+        <row>
+         <entry>
+          (PHP 3, PHP 4 >= 4.0.0)
+         </entry>
+         <entry>
+          strlen() has been around in both all of PHP 3 and PHP 4
+         </entry>
+        </row>
+        <row>
+         <entry>
+          int
+         </entry>
+         <entry>
+          Type of value this function returns, which is an 
+          <link linkend="language.types.integer">integer</link>
+          (i.e. The length of a string is measured in numbers).
+         </entry>
+        </row>
+        <row>
+         <entry>
+          ( string str )
+         </entry>
+         <entry>
+          The first (and in this case the only) parameter/argument for the 
+          function strlen() is named <parameter>str</parameter>, and it's a 
+          <link linkend="language.types.string">string</link>.
+         </entry>
+        </row>
+       </tbody>
+      </tgroup>
+     </table>
+    </para>
+    <para>
+     We could rewrite the above function definition in a generic way:
+    </para>
+    <para>
+     <screen role="html">
+      returned type    function name    ( parameter type   parameter name )
+     </screen>
+    </para>
+    <para>
+     Many functions take on multiple parameters, such as <function>in_array</function>.
+     It's prototype is as follows:
+    </para>
+    <para>
+     <screen role="html">    
+      bool in_array ( mixed needle, array haystack [, bool strict])
+     </screen>
+    </para>
+    <para>
+     What does this mean?  in_array() returns a 
+     <link linkend="language.types.boolean">boolean</link> value, &true; on 
+     success (the <parameter>needle</parameter> was found in the 
+     <parameter>haystack</parameter>) or &false; on failure (the 
+     <parameter>needle</parameter> was not found in the 
+     <parameter>haystack</parameter>).  The first parameter is named 
+     <parameter>needle</parameter> and it can be many different 
+     <link linkend="language.types">types</link>, so we call it 
+     "<emphasis>mixed</emphasis>".  This mixed <parameter>needle</parameter> 
+     (what we're looking for) can either be a scalar value (string, integer, 
+     or <link linkend="language.types.float">float</link>), or an
+     <link linkend="language.types.array">array</link>.  
+     <parameter>haystack</parameter> (the array we're searching in) is the 
+     second parameter.  The third <emphasis>optional</emphasis> parameter is 
+     named <parameter>strict</parameter>.  All optional parameters are seen 
+     in <emphasis>[</emphasis> brackets <emphasis>]</emphasis>.  The manual 
+     states that the <parameter>strict</parameter> parameter defaults to 
+     boolean &false;.  See the manual page on each function for details on 
+     how they work.
+    </para>
+ </sect1>
  
  <sect1 id="about.more">
   <title>How to find more information about PHP</title>