Re: RE: [PHP4BETA] Coding und documentation standards

Leon Atkinson wrote: > > > So, is anybody working on coding and documentation standards? > > I have a style guide for PHP code, and part of it is to put > well-formatted comment blocks at the top each every file > and above function definitions. That Java is so structured > in the first place makes Javadoc a little easier than a > similar system for PHP, but it shouldn't be too hard. > > For example, the function headers I've been writing look > like this: > > /* > ** Function: addToLog > ** Input: STRING message, INTEGER severity > ** Output: none > ** Description: Puts a message in the log > */ > > It might be kind of cool to have comments written in XML, though. > > /* > <function name="addToLog"> > <input name="message" type="string"> > <input name="severity" type="integer"> > <description>Puts a message in the log</decription> > </function> > */ > > I'm not sure that's as readable. > > Anyway, I'm very interested and willing to help out. I've sort of settled with Javadoc for now. I tried doing XML, but it was simply too verbose and clutters up the code/comments too much. But we definitely need a good solution for this in PHP 4 / PEAR. The solutions I have had in mind are: 1. Javadoc with plain text. 2. Javadoc with HTML or XHTML (XML HTML rather than SGML HTML) formatting. The [X]HTML markup would then be translated to DocBook for use in manuals. 3. A reduced XML format that is translated to DocBook like for [2]. 4. DocBook tags in the comments. Here are some examples of what I mean (using PEAR's DB_common::errorCode() method as an example): 1: /** * Map native error codes to DB's portable ones. Requires that * the DB implementation's constructor fills in the $errorcode_map * property. * * @param $nativecode the native error code, as returned by the backend * database extension (string or integer) * * @return int a portable DB error code, or FALSE if this DB * implementation has no mapping for the given error code. */ 2: /** * Map native error codes to DB's portable ones. Requires that * the DB implementation's constructor fills in the <tt>$errorcode_map</tt> * property. * * @param $nativecode int the native error code, as returned by the backend * database extension (string or integer) * * @return int a portable DB error code, or <tt>FALSE</tt> if this DB * implementation has no mapping for the given error code. */ 3: /** * <purpose> * Map native error codes to DB's portable ones. * </purpose> * <desc> * errorCode() requires that the DB implementation's constructor * fills in the <var>$errorcode_map</var> property. * </desc> * <param name="nativecode" type="int"> * the native error code, as returned by the backend database extension * </param> * <return type="int"> * a portable DB error code, or <const>FALSE</const> if this DB implementation * has no mapping for the given error code. * </return> */ 4: /** * <refentry id="pear.DB-common.errorCode"> * <refnamediv> * <refname>errorCode</refname> * <refpurpose>Map native error codes to DB's portable ones.</refpurpose> * </refnamediv> * <refsect1> * <title>Description</title> * <funcsynopsis> * <funcdef>int <function>errorCode</function></funcdef> * <paramdef>int <parameter>nativecode</parameter></paramdef> * </funcsynopsis> * <para> * errorCode() requires that the DB implementation's constructor * fills in the <parameter>$errorcode_map</parameter> property. * </para> * </refsect1> * </refentry> */ Although it is my opinion that [4] is the most complete and flexible solution, [1] is by far the one that is most appealing to the eye (at least mine) when reading the code. However, if someone wants to have this documentation as part of a manual, maybe even the PHP manual in PEAR's case, [1] is out of the question since it allows no markup. [2] and [3] can do the job, but there are lots of problems waiting for you if you define a subset of some DTD people know, because they will always require some new tag. [4] is very verbose and makes it hard to make good use of the docs when reading code. I think I would prefer either [2] (Javadoc + HTML/XHTML) or [4] (DocBook/XML markup). - Stig