![]() |
|
Authoring documents
Documents format
daCode documentation comes in two formats: plain text and a custom "extension" to XML. In any cases, XML is prefered, as it allows easy translation.
If you choose to write doc in plain text, you must follow the following rules:
-
use iso-8859-1 encoding;
-
write it in english if you can;
-
use Unix newlines, as most daCode hackers use Unix variants.
If you choose to write it directly in XML, use DocBook XML 4.1.2. Again, use iso-8859-1 encoding. We may consider switching to iso-8859-15 later, but that won't have much impact.
If you document is written in English, and you cannot contribute any translation, just write plain XML. If you begin to write it in any other language, or want to translate an existing doc, use the following formalism.
Multilingual documents consist of the various translations overlapping. A section specific to one language is enclosed in <:lc and :>, where lc stands for the language code. For exemple, to identify a section in English, one would write <:lc text in English :>. Don't forget the spaces, you may get unexpected results, or even parse errors.
In any case, you shall process you documents using doc/common/scripts/doctranslator.pl to produce the actual XML files. See FIXME for details on using doctranslator.pl.
The HTML documents are auto-generated. Please do not edit them, as all your changes will be lost whenever you upgrade. The special case is the user's guide, which you must edit in order to fit your site. Do it in a copy of doc/user/user-lc directory, out of CVS control.
The api doc is auto generated from source code with PHPDoc (phpdoc.de), thus do not try to edit the HTML version. The format is described below.
PHPDoc comments
The PHPDoc comments are much like JavaDoc, and are use to auto-generate technical documentation. The items to be documented are classes, classes attributes and methods. To get a correct rendering, you may need to hack a bit PHPDoc to have it take into account your line breaks (See PhpdocParserCore::getDescription()). Please also keep in mind that this documentation effort is still under way. If you find something which does not comply to these standards, a correction would be very much appreciated.
Class documentation. A class shall be in it's own file. This file must have a header in the form:
/** * Short description of the class * * Long description... * daCode http://daCode.org * src/dir/filename.php3 * CVS ID tag * * Optionally, dependancies *@author author <authormail> */ Class foobar { ... |
Attribute documentation. An attribute documentation may be much reduced. The only needed infos are its role and its type. For exemple:
/** * Optionnal short description * Optionnal long description *@var type a short description */ var $foo; |
Method documentation. Methods and functions documentation must specify their role, their behaviour, their usage and their side effects. Describe the side-effects in the long description, particularily:
-
any output on standard output;
-
any call to header() or setcookie();
-
any call to exit or die.
/** * Do someting useful * It does something useful. Assumes that a> b and c < d; * it returns the value (b-a) / (d-c). * Calls exit if a < b * Calls header() if c < d (set Content-Type to image/png) * Outputs some data. * *@access public *@param object BigInt $a first param *@param object BigInt $b second param (this is b) *@param int $c third *@param int $d four *@return int (b-a) / (d-c) if valid arguments, -1 otherwise. */ Function foobar($a, $b, $c, $d) { ... |
The formatting must comply with the following rules:
-
Each comment line shall start with tabs to indent up to the level of the declaration it documents, then a space and an asterisk (*).
-
The first line of a PHPDoc comment shall begin with tabs up to the indentation level of the decalration it documents, followed by a slash (/) and two asterisks (**).
-
There shall be a space between the asterisk a start of a line and the text. This rule do not apply to lines containing a tag (@something). You may put a space betweew * and @ if you like.
-
There should be a @access tag. Please do not forget it in the doc you write.
Languages
As said above, we use a special formalism to manage translations. The primary language for documentation is English; we do our best to keep the French translations of user and webmaster's documentaion up in sync.
Other languages are welcome, but they are not considered a priority, since most of daCode users and contributors are French. Documentation intended for the developers are often not translated, and this is not a priority, since the code is written in English; thus you must at least understand English to contribute code.