As Goba said, there was a little problem with wrapping. As you are new to the PHP documentation world, I've decided to correct your file and comment the difference between your orignal work and my review. Let's begin :)
--- ircg_list.xml Thu Jan 29 11:11:35 2004 +++ ircg-list.xml Thu Jan 29 10:58:20 2004
[COMMENT: the filename shouldn't have any underscore, so we s/_/-/ => ircg-list.xml is the good filename]
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.1 $ -->
<refentry id="function.ircg-list">
<refnamediv>
<refname>ircg_list</refname>
@@ -8,28 +8,33 @@
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>bool</type> <methodname>ircg_list</methodname>
- <methodparam><type>resource</type> <parameter>connection</parameter></methodparam>
- <methodparam><type>string</type> <parameter>channel</parameter></methodparam>
+ <type>bool</type><methodname>ircg_list</methodname>
+ <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <methodparam><type>string</type><parameter>channel</parameter></methodparam>
[COMMENT : no space between </type> and <parameter> or <methodname>]
</methodsynopsis>
<simpara>
- <function>ircg_list</function> will request a list of users in the <variable>channel</variable>. The answer is sent to the output defined by <function>ircg_set_file</function> or <function>ircg_set_current</function>. Returns <literal>TRUE</literal> on success.
+ <function>ircg_list</function> will request a list of users in the
+ <parameter>channel</parameter>. The answer is sent to the output
[COMMENT : <variable> seems to cause some problems with make test. Plus, when we are talking about an argument, we use <parameter>]
+ defined by <function>ircg_set_file</function> or + <function>ircg_set_current</function>.
[COMMENT : I've splitted the line, for wrapping reasons]
+ &return.success;
[COMMENT : We have an entity for the boolean return : This function will return TRUE on success, FALSe on failure. (or something like that)]
</simpara>
<para>
<example>
- <title>Usage</title>
+ <title><function>ircg_list</function> example</title>[COMMENT : let's have a more explicit title ;)]
<programlisting role="php"> <![CDATA[ -// connect to server with nick, ip (!) and port (6667) +<?php
[COMMENT : if it's a PHP example, let's use PHP tags]
+ +// connect to server
[COMMENT : let's the comment be short and more generic (port number)
As for the (!) after ip, the documentation for ircg_pconnect already claims that IP should be in numerical form]
$id = ircg_pconnect($nickname, $ip, $port);
// set to output to a file ircg_set_file($id, 'irc_output.html');
// try to join a channel
-if (!ircg_join($id, $channel))
-{
- echo 'Cannot /join $channel<br />';
+if (!ircg_join($id, $channel)) {
+ echo "Cannot /join $channel<br />";
}[COMMENT : Coding standards. Also, don't ever use any tabulation in an XML file :)]
// send list command
@@ -44,18 +49,26 @@
// output everything
readfile('irc_output.html');-/* output: +?> +]]> + </programlisting> + <para> + This example will output something similar to: + </para> + <screen> +<![CDATA[ ... Channel #channel has n users and the topic is 'Topic' End of LIST ... -*/ ]]> - </programlisting> + </screen>
[COMMENT : when the output is more than one line (for an echo for example), we try to use the <screen> notation]
</example>
</para>
<simpara>
- See also <function>ircg_set_file</function>, <function>ircg_set_current</function>, <function>ircg_who</function>.
+ See also <function>ircg_set_file</function>,
+ <function>ircg_set_current</function>, and
+ <function>ircg_who</function>.
[COMMENT : wrapping, and added an "and"]
</simpara>
</refsect1>
- </refentry>
\ No newline at end of file
+ </refentry>I hope that I didn't miss anything ;) Thank you a lot for your work, it's really good for a first approach !
didou
Gabor Hojtsy wrote:
Hi David!
We do manual wrapping on XML files, so in place of lines 16 and 58 in the file you sent more lines should be present after wrapping... Otherwise (given that I don't have a clue on ircg :), the docs seem to be fine.
Goba
David Costa wrote:
Resending from another mailserver, the previoous attachment was defanged. Sorry David
Begin forwarded message:
From: David Costa <[EMAIL PROTECTED]> Date: January 29, 2004 5:46:07 AM CET To: [EMAIL PROTECTED] Cc: Mehdi Achour <[EMAIL PROTECTED]> Subject: New doc: ircg_list
Hello Mehdi and All,
As suggested I started off with "documenting some undocumented functions"
The lucky "orphan" ;) is ircg_list
If you like it, I would be more then glad continue with the other "orphan" members of the ircg family (I have almost finished ircg_who and ircg_invite).
It's my first doc, I would appreciate your comments/corrections/suggestions.
Thanks in advance for your patience and assistance,
David
P.S. I did tested the function extensively before writing the doc.
