On Sat, 22 Nov 2003, Gabor Hojtsy wrote:
> >>The DOMXML extension has this kind of documentation.
> >
> > No, DOMXML only supports OO-Syntax, not OO and procedural style.
> > Also class->method is hard to read instead to have a list of properties and
> > methods for different objects.
>
> Well, the dir class has some true OO documentation, but there is not
> much real OO docs in the XML sources.
>
> The dir class uses classsynopsys:
> http://www.docbook.org/tdg/en/html/classsynopsis.html
>
> This enables you to provide an overwiev of the class, but does not let
> you add documentation for methods or attributes. I would suggest you
> document the mysqli class with this syntax on the intro page of the
> mysqli section, and then note on each function page that there is an OO
> syntax to use it.
>
> Unfortunately I have never used DocBook to document OO stuff, so I have
> no personal experience.
But I did, see http://www.vl-srm.net/doc/class.srmapp.php (it needs a
bit of tweaking though as the constructor doesn't look good yet).
I tweaked some of the DSSSL that I copied from the PHP Doc stuff, and
backporting it is possible, it just takes a bit of time. The XML for
this is attached.
Derick
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.85 $ -->
<reference id="classes">
<title>Class reference</title>
<!-- ********************************************************************* -->
<refentry id="class.srm">
<refnamediv>
<refname>Class SRM</refname>
<refpurpose>
This class is used to establish and maintain a connection to the SRM
Daemon.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<classsynopsis>
<ooclass>
<classname>SRM</classname>
</ooclass>
<constructorsynopsis>
<methodparam><type>string</type><parameter>host</parameter></methodparam>
<methodparam><type>int</type><parameter>port</parameter></methodparam>
</constructorsynopsis>
<fieldsynopsis>
<type>array</type><varname>globals</varname>
</fieldsynopsis>
<methodsynopsis>
<type>mixed</type><methodname>function</methodname>
<methodparam><parameter>...</parameter></methodparam>
</methodsynopsis>
</classsynopsis>
<para>
The <classname>SRM</classname> class maintains the connection with the
daemon. It also manages <link linkend="class.srm.global-vars">global
variables</link> and an interface to the <link
linkend="class.srm.module-functions">functions</link> in the
extension modules.
</para>
<refsect2 id="class.srm.constructor">
<title>Constructor</title>
<constructorsynopsis>
<methodparam><type>string</type><parameter>host</parameter></methodparam>
<methodparam><type>int</type><parameter>port</parameter></methodparam>
</constructorsynopsis>
<para>
The class constructor connects the script to the SRM daemon. There
are two parameters necessary for this to be accomplished. The
<parameter>host</parameter> parameter is the IP address of the machine
where the SRM daemon is running. The second parameter is the
<parameter>port</parameter> on which the specificed SRM daemon is
listening for incoming connection requests. The example below
makes a connection to an SRM daemon on the same
<parameter>host</parameter>, running on <parameter>port</parameter> 7777
(the default port).
</para>
<para>
<example>
<title>Connecting to an SRM Daemon</title>
<programlisting><?php
$con = new SRM ('localhost', 7777);
?></programlisting>
</example>
</para>
</refsect2>
<refsect2 id="class.srm.global-vars">
<title>Global variables</title>
<para>
The <classname>SRM</classname> class is capable of managing global
variables for an application. These global variables are stored within
the SRM daemon, and are accessible to every script connected to the
daemon. It's possible to access the global variables with the
<varname>globals</varname> array found within the SRM object. The example
below shows how to set and get these variables.
</para>
<para>
<example>
<title>Using global variables</title>
<programlisting><?php
/* make a connection to the daemon */
$con = new SRM ('localhost', 7777);
/* set the global variable 'foo' to 807 */
$con->globals['foo'] = 807;
/* display the contents of global variable 'bar' */
echo $con->globals['bar'];
?></programlisting>
</example>
</para>
</refsect2>
<refsect2 id="class.srm.module-functions">
<title>Functions</title>
<para>
Explain the function library (written in PHP) and calling functions in
SRM modules.
</para>
</refsect2>
</refsect1>
</refentry>
<!-- ********************************************************************* -->
<refentry id="class.srmapp">
<refnamediv>
<refname>Class SRMApp</refname>
<refpurpose>
Instantiate a class on the remote Daemon.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<classsynopsis>
<ooclass>
<classname>SRMApp</classname>
</ooclass>
<constructorsynopsis>
<methodname>SRMApp</methodname>
<methodparam><type>resource</type><parameter>srm</parameter></methodparam>
<methodparam><type>string</type><parameter>application_id</parameter></methodparam>
</constructorsynopsis>
<fieldsynopsis>
<type>int</type><varname>handle</varname>
</fieldsynopsis>
<fieldsynopsis>
<type>mixed</type><varname>varname</varname>
</fieldsynopsis>
<methodsynopsis>
<type>void</type>
<methodname>__abort</methodname>
<void/>
</methodsynopsis>
<methodsynopsis>
<type>mixed</type>
<methodname>function</methodname>
<methodparam><type>mixed</type><parameter>parameter</parameter></methodparam>
<methodparam><parameter>...</parameter></methodparam>
</methodsynopsis>
</classsynopsis>
<para>
The class <classname>SRMApp</classname> is able to work with remote
objects. After instantiating the class, it is possible to interact with a
remote object exactly like if the object was instatiated in a local script.
</para>
<refsect2>
<title>Constructor</title>
<constructorsynopsis>
<methodname>SRMApp</methodname>
<methodparam><type>object</type><parameter>srm</parameter></methodparam>
<methodparam><type>string</type><parameter>application_id</parameter></methodparam>
</constructorsynopsis>
<para>
The <parameter>srm</parameter> is an <classname>SRM</classname> object as
returned by the constructor like so: <literal>$obj = new SRM()</literal>.
The <parameter>application_id</parameter> is the name of the
<classname>Banana</classname> desired to be accessed remotely. The
<classname>Banana</classname> will be started if one was not already
started. The handle to a <classname>Banana</classname> is stored in
the object property <varname>handle</varname>. If a
<classname>Banana</classname> was already running, only the handle is
returned. In both cases this constructor returns an
<classname>SRMApp</classname> object that can be used within the script.
</para>
<!-- What name are we going with ?!?!?! Lets decide is it an SRMApp or
is it a Banana? Work with me people! -Dan -->
</refsect2>
<refsect2>
<title>Properties</title>
<fieldsynopsis>
<type>int</type><varname>handle</varname>
</fieldsynopsis>
<para>
This property contains a unique identifier to the remote
<classname>Banana</classname>. This property should never be altered by a
user, and should be considered read-only. In the future, the handle
system might go away when the extension is ported over to ZendEngine 2.
</para>
<fieldsynopsis>
<type>mixed</type><varname>varname</varname>
</fieldsynopsis>
<para>
Other properties may be used with this object, and are handled like
standard properties to a generic PHP Class. The example below shows
the difference between a local class, and a remote
<classname>Banana</classname> class.
</para>
<para>
<example>
<title>Local and remote objects</title>
<programlisting><?php
/* local object */
$l_uptime = new Uptime;
echo $l_uptime->current_uptime."\n";
/* remote object */
$srm = new SRM ('localhost', 7777);
$r_uptime = new SRMApp ($srm, 'Uptime');
echo $r_uptime->current_uptime."\n";
?></programlisting>
</example>
</para>
</refsect2>
<refsect2 id="class.srmapp.members">
<title>Member functions</title>
<methodsynopsis>
<type>void</type>
<methodname>__abort</methodname>
<void/>
</methodsynopsis>
<para>
The <function>__abort</function> member function causes a remote
<classname>Banana</classname> to stop executing. This forces a
<classname>Banana</classname>'s eventloop to end, returning a value to the
<function>run</function> member function of the
<classname>Banana</classname>. This function can be used to force
a <classname>Banana</classname> to be reloaded from a disk. To reload
an aborted <classname>Banana</classname>, creating a new
<function>SRMApp</function> will cause the SRM daemon to re-read the
script from disk.
</para>
<methodsynopsis>
<type>mixed</type>
<methodname>function</methodname>
<methodparam><type>mixed</type><parameter>parameter</parameter></methodparam>
<methodparam><parameter>...</parameter></methodparam>
</methodsynopsis>
<para>
As with properties to the <classname>SRMApp</classname> objects,
functions work the same way. The example below shows how to call a
function of a remote class.
</para>
<para>
<example>
<title>Calling member functions in remote objects</title>
<programlisting><?php
/* remote object */
$srm = new SRM ('localhost', 7777);
$uptime = new SRMApp ($srm, 'Uptime');
/* reset the uptime on the remote object */
echo $uptime->reset_uptime()."\n";
?></programlisting>
</example>
</para>
</refsect2>
</refsect1>
</refentry>
<!-- ********************************************************************* -->
<refentry id="class.banana">
<refnamediv>
<refname>Class Banana</refname>
<refpurpose>
This is the virtual class for Banana objects.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<classsynopsis>
<ooclass>
<classname>Banana</classname>
</ooclass>
<methodsynopsis>
<type>void</type><methodname>run</methodname>
<void/>
</methodsynopsis>
</classsynopsis>
<para>
A <classname>Banana</classname> is a virtual class that should never
be directly instantiated. Instead any use of a
<classname>Banana</classname> should be done through an inherited class.
See the <link linkend="user.bananas.writing">Writing
Banana components</link> section of the manual for more information
and examples.
</para>
<refsect2>
<title>Member functions</title>
<methodsynopsis>
<type>void</type><methodname>run</methodname>
<void/>
</methodsynopsis>
<para>
A <classname>Banana</classname> has only one member function, which
initializes the eventloop. The eventloop dispatches requests made to
the <classname>Banana</classname> from the client. See
<link linkend="user.bananas.eventloop">The eventloop of Bananas</link>
section of the manual for more information and examples.
</para>
</refsect2>
</refsect1>
</refentry>
</reference>
<!-- keep this comment at the end of the file
vim600: syn=xml fen fdm=syntax fdl=4 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
