Re: Patch for documentation

Hi Hannes, Ah thanks for that. I've attached another diff (unified this time). Hopefully this will be a bit more useable. I'll push on with the existing templates for now, and if I get time later have a look at helping out with creating some new templates. You've probably been asked this before - is there a whitespace checking/formatting tool available? Many thanks, Tony Hannes Magnusson wrote: > On Tue, Aug 19, 2008 at 16:43, Anthony Bedford <Tony.Bedford@sun.com> wrote: >> Hi, >> >> I've created a small patch for the documentation. Could someone please check >> the patch? If it's OK please feel free to check it into CVS. >> >> Many thanks, >> Tony >> >> ---- >> Tony Bedford, Technical Writer >> Database Technology Group, Sun Microsystems >> http://sun.com | >> http://mysql.com >> >> Index: en/reference/mysqli/mysqli_stmt/attr-get.xml >> =================================================================== >> RCS file: /repository/phpdoc/en/reference/mysqli/mysqli_stmt/attr-get.xml,v >> retrieving revision 1.2 >> diff -r1.2 attr-get.xml > > We really prefer unified diffs (diff -u) as they are much simpler to read :) > >> 7c7 >> < <refpurpose></refpurpose> >> --- >>> <refpurpose/> > > So... that function/method has no purpose? :) > >> 10,11c10 >> < <refsect1 role="description"> >> < &reftitle.description; >> --- >>> <refsect1 role="description"> &reftitle.description; >>> <para>Object > > We have a very strict WS convention which we would appreciate to be > kept in tact :) > See http://wiki.php.net/doc/articles/whitespace for a fun read. > Please see the skeleton files (phpdoc/RFC/skeleton/*.xml) for correct structure > >>> oriented style (method):</para> >> 13,15c12,17 >> < >> <type>int</type><methodname>mysqli_stmt_attr_get</methodname> >> < >> >> <methodparam><type>mysqli_stmt</type><parameter>stmt</parameter></methodparam> >> < >> <methodparam><type>int</type><parameter>attr</parameter></methodparam> >> --- >>> <type>int</type> >>> <methodname>mysqli_stmt::attr_get</methodname> >>> <methodparam> >>> <type>int</type> >>> <parameter>attr</parameter> >>> </methodparam> >> 16a19,33 >>> <para>Procedural style:</para> >>> <methodsynopsis> >>> <type>int</type> >>> <methodname>mysqli_stmt_attr_get</methodname> >>> <methodparam> >>> <type>mysqli_stmt</type> >>> <parameter>stmt</parameter> >>> </methodparam> >>> <methodparam> >>> <type>int</type> >>> <parameter>attr</parameter> >>> </methodparam> >>> </methodsynopsis> > > The WS is all wrong again here. Other than that, seems fine. > > >>> <para>Used to get the current value for a statement attribute. </para> >>> </refsect1> >> 18c35,46 >> < &warn.undocumented.func; >> --- >>> <refsect1 role="parameters"> &reftitle.parameters; <para> >>> <variablelist> &mysqli.stmt.description; <varlistentry> > > WS.. > > > [..] >> 19a48,49 >>> <refsect1 role="returnvalues"> &reftitle.returnvalues; >>> <para>Returns >>> FALSE if the attribute is >>> not found, otherwise returns the value of the attribute.</para> > > WS :) > > > Looks OK. > > The extension is very annoying with seemingly random usage of > properties and methods using weird prefixes for the procedural > functions that don't map directly to the classnames.. > This is going to be hell to document, can't say that I envy you :P > > Maybe it would be best to identify all the various `method/properties > <-> functions and classname <-> function prefixes` > mappings and then > create a better templates for the extension? > I'm not really sure if the existing method.xml (phpdoc/RFC/skeletons/) > are good enough... > > -Hannes