cvs: phpdoc-ru /appendices about.xml

From: Date: Tue, 01 Jun 2004 14:50:16 +0000
Subject: cvs: phpdoc-ru /appendices about.xml
Groups: php.doc.ru 
Request: Send a blank email to doc-ru+get-353@lists.php.net to get a copy of this message
young Tue Jun 1 10:50:16 2004 EDT Modified files: /phpdoc-ru/appendices about.xml Log: Add two lost chapters to Appendix O. It will be translated soon. http://cvs.php.net/diff.php/phpdoc-ru/appendices/about.xml?r1=1.3&r2=1.4&ty=u Index: phpdoc-ru/appendices/about.xml diff -u phpdoc-ru/appendices/about.xml:1.3 phpdoc-ru/appendices/about.xml:1.4 --- phpdoc-ru/appendices/about.xml:1.3 Wed Sep 4 15:20:38 2002 +++ phpdoc-ru/appendices/about.xml Tue Jun 1 10:50:16 2004 @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="windows-1251"?> <!-- EN-Revision: 1.16 Maintainer: tronic Status: ready --> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <!-- TODO: add manual conventions section (eg. how to read @@ -119,6 +119,174 @@ </note> </sect1> + <sect1 id="about.prototypes"> + <title>How to read a function definition (prototype)</title> + <para> + Each function in the manual is documented for quick reference. Knowing how + to read and understand the text will make learning PHP + much easier. Rather than relying on examples or cut/paste, you will 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 loosely 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> +strlen + +(PHP 3, PHP 4, PHP 5) +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, PHP 5) + </entry> + <entry> + strlen() has been around in all versions of PHP 3, PHP 4 and PHP 5 + </entry> + </row> + <row> + <entry> + int + </entry> + <entry> + Type of value this function returns, which is an + <type>integer</type> (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 this + function is named <parameter>str</parameter>, and it's a + <type>string</type>. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + We could rewrite the above function definition in a generic way: + </para> + <para> + <screen> + returned type function name ( parameter type parameter name ) + </screen> + </para> + <para> + Many functions take on multiple parameters, such as <function>in_array</function>. + Its prototype is as follows: + </para> + <para> + <screen> + 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 (if the <parameter>needle</parameter> was found in the + <parameter>haystack</parameter>) or &false; on failure (if the + <parameter>needle</parameter> was not found in the + <parameter>haystack</parameter>). The first parameter is named + <parameter>needle</parameter> and it can be of 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 be either 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> + <para> + There are also functions with more complex PHP version information. Take + <function>html_entity_decode</function> as an example: + </para> + <para> + <screen> + (PHP 4 >= 4.3.0, PHP 5) + </screen> + </para> + <para> + This means that this function was not available in PHP 3, and is only + available in a released version since PHP 4.3.0. + </para> + </sect1> + + <sect1 id="about.phpversions"> + <title>PHP versions documented in this manual</title> + <para> + This documentation contains information about bot PHP 4 and PHP 5, with + some added migration and compatibility notes regarding PHP 3. Behaviour, + parameter, return value and other changes between different PHP + versions are documented in notes and inline text in the manual. + </para> + <para> + You may find documentation pieces for the CVS version of PHP, which + always means the very latest development version available through + the CVS version handling system. If you are not a developer of PHP + itself, and you are not keen on using the very latest development + version of PHP, features marked with the "available in CVS" wording + are not accessible to you. These features, though, will probably be + available in the next stable version of PHP. If you would like to + download the CVS version, see the <ulink url="&url.php.anoncvs;">anonymous + CVS access page</ulink>. + </para> + <para> + You may also encounter documentation for a PHP version which is + not released (something like PHP 5.0.0 while the latest stable version + is 4.3.x). Most of the time, this is not an error in the documentation. + Explanation is often added for features not available in the current + PHP release, but which will be available in a known future PHP version. + </para> + </sect1> + <sect1 id="about.more"> <title>Êàê óçíàòü áîëüøå î PHP</title> <para>

« previous php.doc.ru (#353) next »