complete counter extension documentation, change base ID of new internals docs FROM book.internals2 TO internals2 - consistency and proper scoping

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@258732 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gwynne Raskind 2008-04-29 11:33:03 +00:00
parent 079e80887e
commit 456e4db2f9

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<part xml:id="internals2.counter" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>The "counter" Extension - A Continuing Example</title>
@ -373,6 +373,7 @@ class MyCounter extends Counter
}
}
Counter::setCounterClass("MyCounter");
if (($counter_one = Counter::getNamed("one")) === NULL) {
$counter_one = new Counter("one", 0, COUNTER_FLAG_PERSIST);
}
@ -667,8 +668,438 @@ $counter_four->printCounterInfo();
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.counter-class.setCounterClass">
<refnamediv>
<refname>Counter::setCounterClass</refname>
<refpurpose>
Set the class returned by <methodname>Counter::getNamed</methodname>.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>static</modifier>
<type>void</type><methodname>Counter::setCounterClass</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>Counter::setCounterClass</function> changes the class of objects
returned by <function>Counter::getNamed</function>. The class being set
must not have a public constructor and must be a subclass of
<classname>Counter</classname>. If these conditions are not met, a fatal
error is raised. This is a static function.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<simpara>
The name of the class to use.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
</reference>
<reference xml:id="internals2.counter.basic-interface">
<title>The basic interface</title>
<titleabbrev>Basic</titleabbrev>
<refentry xml:id="internals2.counter.function.counter-get">
<refnamediv>
<refname>counter_get</refname>
<refpurpose>
Get the current value of the basic counter.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>integer</type><methodname>counter_get</methodname>
<void/>
</methodsynopsis>
<simpara>
<function>counter_get</function> returns the current value of the basic
interface's counter.
</simpara>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
<function>counter_get</function> returns an integer.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>counter_bump</function></member>
<member><function>counter_reset</function></member>
</simplelist>
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.function.counter-bump">
<refnamediv>
<refname>counter_bump</refname>
<refpurpose>
Update the current value of the basic counter.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>counter_bump</methodname>
<methodparam><type>integer</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>counter_bump</function> updates the current value of the basic
interface's counter.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<simpara>
The amount by which to change the counter's value. Can be negative.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>counter_get</function></member>
<member><function>counter_reset</function></member>
</simplelist>
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.function.counter-reset">
<refnamediv>
<refname>counter_reset</refname>
<refpurpose>
Reset the current value of the basic counter.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>counter_reset</methodname>
<void/>
</methodsynopsis>
<simpara>
<function>counter_reset</function> resets the current value of the basic
interface's counter to its original initial value.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>counter_get</function></member>
<member><function>counter_bump</function></member>
</simplelist>
</refsect1>
</refentry>
</reference>
<reference xml:id="internals2.counter.extended-interface">
<title>The extended interface</title>
<titleabbrev>Extended</titleabbrev>
<refentry xml:id="internals2.counter.function.counter-create">
<refnamediv>
<refname>counter_create</refname>
<refpurpose>
Creates a counter which maintains a single numeric value.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>counter_create</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam choice="opt"><type>integer</type><parameter>initial_value</parameter></methodparam>
<methodparam choice="opt"><type>integer</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<simpara>
Creates a counter which maintains a single numeric value.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<simpara>
The new counter's name.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>initial_value</term>
<listitem>
<simpara>
The initial value of the counter. Defaults to zero (0).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>flags</term>
<listitem>
<simpara>
Flags for the new counter, chosen from the
<literal>COUNTER_FLAG_*</literal> constants.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Returns a counter resource.
</simpara>
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.function.counter-get-value">
<refnamediv>
<refname>counter_get_value</refname>
<refpurpose>
Get the current value of a counter resource.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>integer</type><methodname>counter_get_value</methodname>
<methodparam><type>resource</type><parameter>counter</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>counter_get_value</function> returns the current value of a
counter resource.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>counter</parameter></term>
<listitem>
<simpara>
The counter resource to operate on.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
<function>counter_get_value</function> returns an integer.
</simpara>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>counter_bump_value</function></member>
<member><function>counter_reset_value</function></member>
</simplelist>
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.function.counter-bump-value">
<refnamediv>
<refname>counter_bump_value</refname>
<refpurpose>
Change the current value of a counter resource.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>counter_bump_value</methodname>
<methodparam><type>resource</type><parameter>counter</parameter></methodparam>
<methodparam><type>integer</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>counter_bump_value</function> updates the current value of a
counter resource.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>counter</parameter></term>
<listitem>
<simpara>
The counter resource to operate on.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<simpara>
The amount by which to change the counter's value. Can be negative.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>counter_get_value</function></member>
<member><function>counter_reset_value</function></member>
</simplelist>
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.function.counter-reset-value">
<refnamediv>
<refname>counter_reset_value</refname>
<refpurpose>
Reset the current value of a counter resource.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>void</type><methodname>counter_reset_value</methodname>
<methodparam><type>resource</type><parameter>counter</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>counter_reset_value</function> resets the current value of a
counter resource to its original initial value.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>counter</parameter></term>
<listitem>
<simpara>
The counter resource to operate on.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><function>counter_get_value</function></member>
<member><function>counter_bump_value</function></member>
</simplelist>
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.function.counter-get-meta">
<refnamediv>
<refname>counter_get_meta</refname>
<refpurpose>
Return a piece of metainformation about a counter resource.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>counter_get_meta</methodname>
<methodparam><type>resource</type><parameter>counter</parameter></methodparam>
<methodparam><type>integer</type><parameter>attribute</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>counter_get_meta</function> returns metainformation about a
counter resource.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>counter</parameter></term>
<listitem>
<simpara>
The counter resource to operate on.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>attribute</parameter></term>
<listitem>
<simpara>
The metainformation to retrieve.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
<function>counter_get_meta</function> returns values of varying types
based on which metainformation was requested.
</simpara>
</refsect1>
</refentry>
<refentry xml:id="internals2.counter.function.counter-get-named">
<refnamediv>
<refname>counter_get_named</refname>
<refpurpose>
Retrieve an existing named counter as a resource.
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>Counter::getNamed</methodname>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
<simpara>
<function>counter_get_named</function> returns an existing counter by name
if that name exists, or &null; otherwise.
</simpara>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<simpara>
The counter name to search for.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
<function>counter_get_name</function> returns an existing counter by name
if that name exists, or &null; otherwise.
</simpara>
</refsect1>
</refentry>
</reference>
</part>
<!-- Keep this comment at the end of the file