Author: Derick Rethans Date: 2006-08-29 11:00:10 +0200 (Tue, 29 Aug 2006) New Revision: 3414
Log: - Added more information to the development process and brough the other documents up to date. Modified: docs/guidelines/dev_process.txt docs/guidelines/source_documentation.txt docs/test_environment.txt Modified: docs/guidelines/dev_process.txt =================================================================== --- docs/guidelines/dev_process.txt 2006-08-29 08:46:19 UTC (rev 3413) +++ docs/guidelines/dev_process.txt 2006-08-29 09:00:10 UTC (rev 3414) @@ -12,11 +12,11 @@ Always follow the 5 phase development process: -1. Write Requirements document and Design specifications -2. Write API stubs with parameter documentation and descriptions -3. Write test cases -4. Implement classes -5. Write extra documentation and tutorial +1. `Write Requirements document and Design specifications`_. +2. `Write API stubs with parameter documentation and descriptions`_. +3. `Write test cases`_. +4. `Implement classes`_. +5. Write extra documentation and `tutorial`_. The specs are stored in SVN (http://svn.ez.no/svn/ezcomponents/packages/<component>/trunk/design). And a @@ -27,7 +27,78 @@ The full development is done in SVN and new components can only be added by `maintainers`_. +Write Requirements document and Design specifications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Before the requirements documents and design specifications are written an +idea for a new component should be announced on the `components mailinglist`_. +This is to make sure that only components are developed which fit into +our global idea of "high quality components for web application development". +Based on the ideas that are outlined on the list we will make a decision +whether we are interested in making a component part of the eZ components +library. + +While introducing a new component the following information should be present: + +- What is the component about? +- Which features will it provide? +- A rationale why it should be part of the components. + +After the component has been announced, discussed and approved it is time +to start writing the Requirements document and Design specifications. At +this point we will create a directory in the experimental directory where +the documents can be stored while waiting for feedback. At this same time +some prototyping can be done as well there. + +The Requirements document and Design specifications are most likely going +to attract feedback as well. This is supposed to be a creative and iterative +process which means that proceeding to the next phase should not commence +before the documents have been approved as well. + +There is also more information on how to structure the `Requirements document`_ +and `Design specifications`_. + +.. _`components mailinglist`: http://lists.ez.no/mailman/listinfo/components +.. _`Requirements document`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/requirements_doc.txt +.. _`Design specifications`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/design_doc.txt + +Write API stubs with parameter documentation and descriptions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This should serve as some prototyping to see how the code could work. As part +of the API stubs you can already create the files with the classes and methods +that you think your API needs. Often this will result from some protyping +and ofcourse the design document. To complete this phase there should +be an example in the main classes` doc blocks and API documentation for +each constant, variable, property and method. Of course during development +some things might change. This first initial implementation of the stubs just +serves as a little playground. It is important that *no* implementation code +is written during this phase. After the API stubs are written and committed +to SVN (still in the `experimental`_ directory) a mail should be send to +the `components mailinglist`_ to ask for feedback. Documentation of classes +is done with the `phpDocumentor`_ syntax. A `small introduction`_ on how to +use it for the components is available as well. + +.. _`experimental`: http://svn.ez.no/svn/ezcomponents/experimental/ +.. _`phpDocumentor`: http://phpdoc.org +.. _`small introduction`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/source_documentation.txt + +Write test cases +~~~~~~~~~~~~~~~~ + +Test cases are written for PHPUnit, see the documentation on how to `set-up the test environment`_. + +.. _`set-up the test environment`: http://svn.ez.no/svn/ezcomponents/docs/test_environment.txt + +Implement classes +~~~~~~~~~~~~~~~~~ + +There are many guidelines for implementing classes and methods. Please refer to +the `guidelines`_. + +.. _`guidelines`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/ + + Bugs ---- @@ -90,3 +161,12 @@ maintainers ----------- More than one `maintainer`_. + +.. _`tutorial`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/tutorial.txt + +.. + Local Variables: + mode: rst + fill-column: 79 + End: + vim: et syn=rst tw=79 Modified: docs/guidelines/source_documentation.txt =================================================================== --- docs/guidelines/source_documentation.txt 2006-08-29 08:46:19 UTC (rev 3413) +++ docs/guidelines/source_documentation.txt 2006-08-29 09:00:10 UTC (rev 3414) @@ -38,13 +38,13 @@ Example: :: /** - * Short description of the contents of the file. - * - * @version //autogen// - * @package PackageName - * @copyright Copyright (C) 2005 eZ systems as. All rights reserved. - * @license http://ez.no/licenses/new_bsd New BSD License - */ + * Short description of the contents of the file. + * + * @version //autogen// + * @package PackageName + * @copyright Copyright (C) 2005 eZ systems as. All rights reserved. + * @license http://ez.no/licenses/new_bsd New BSD License + */ Class documentation =================== @@ -57,8 +57,6 @@ to use the class. - @package - @version -- @copyright -- @license The following fields are optional @@ -69,52 +67,32 @@ Example: :: /** - * One line description of the class. - * - * Extensive documentation of the class. Feel free to use some - * inline code. For example, the following code is "like this": - * <code> - * $archive = new ezcArchive( "/tmp/archive.tar.gz" ); - * $entry = $archive->getEntry(); - * print( "First entry in the archive: " . $entry->getPath() ); - * </code> - * - * Continue documentation. - * - * @example ezcomponents/packages/ezcArchive/examples/my_example.php - * - * @see all_related_classes - * @uses other_packages - * - * @package PackageName - * @version //autogen// - */ + * One line description of the class. + * + * Extensive documentation of the class. Feel free to use some + * inline code. For example, the following code is "like this": + * <code> + * $archive = new ezcArchive( "/tmp/archive.tar.gz" ); + * $entry = $archive->getEntry(); + * print( "First entry in the archive: " . $entry->getPath() ); + * </code> + * + * Continue documentation. + * + * @see all_related_classes + * @uses other_packages + * + * @package PackageName + * @version //autogen// + */ Structured arrays ----------------- -Due to efficiency reasons we use a lot of "struct" like associative arrays in -our Components. Publicially exposed arrays must be documented in the class -header in the following way: :: +Due to efficiency reasons we use a lot of "struct" like objects in +our Components instead of associative arrays. Those should be documented just +like normal classes. - ... - array name_of_your_array - name_of_your_array["key_name1"] Explanation here - name_of_your_array["key_name2"] Explanation here - ... -Example: :: - - This is the structure you want to document: - array( "email" => "[EMAIL PROTECTED]", "name" => "Frederik Holljen" ); - - Snipet of the code that should go in the class header: - ... - array email_address - email_address["email"] The actual email address. - email_address["name"] The name of the address owner. - ... - - Method documentation ==================== Required for all methods and functions @@ -143,9 +121,9 @@ Example 1: (With object parameters) :: - /** - * Returns the length of the line defined in the two dimensional space - * between point1 and point2. + /** + * Returns the length of the line defined in the two dimensional space + * between $point1 and $point2. * * Example: * <code> @@ -155,7 +133,6 @@ * $length = getLength( $point1, $point2 ); * </code> * - * * @see getLength3D() * * @throws PointException if any of the points are imaginary. @@ -163,31 +140,16 @@ * @param Point $point2 * @return int */ + public function getLength2D( Point $point1, Point $point2 ) + { - Generates something like: - int calculateLength( Point point1, Point point2 ) - Returns the length of the line defined in two dimensional space between - point1 and point2. - - -- - $point1 = new Point( 5, 10 ); - $point2 = new Point( 15, 42 ); - - $length = getLength( $point1, $point2 ); - -- - - Returns: int - Parameters: - Point $point1 - Point $point2 - Note how the parameters are not documented since they are already mentioned in the description. Example2: (Same as above but with optional extra parameter and array arguments):: - /* + /** * Returns the length of the line defined in two dimensional space * between point1 and point2. * @@ -196,19 +158,8 @@ * @param int $multiplier Multiplies the result by the given factor. * @return int */ - - Generates something like: - int calculateLength( array point1, array point2, int multiplier = 1 ) - Returns the length of the line defined in two dimensional space between - point1 and point2. - Returns: int - Parameters: - Point $point1 Format array( 'x' => int, 'y' => int ) - Point $point2 Format array( 'x' => int, 'y' => int ) - int multiplier Multiplies the result by the given factor. - -Note how the additional optional parameter _is_ documented since it is not +Note how the additional optional parameter *is* documented since it is not mentioned in the normal description. Of course in this case you could choose to mention it there instead. @@ -254,13 +205,13 @@ - Parameters can be documented in either of the following styles: :: - /* + /** * @param array(int) $somewhatLongerName A long description of - * myParameter and it doesn't - * fit with the 79 characters. + * myParameter and it doesn't + * fit with the 79 characters. */ - /* + /** * @param array(int) $somewhatLongerName * A long description of myParameter and it doesn't fit with the 79 * characters. @@ -274,26 +225,33 @@ Documenting \_\_set and \_\_get ------------------------------- -If you use class properties through simple setting and getting they should be -documented like this:: +If you use class properties then the __set and __get methods get the following +documentation:: - /** + /** * Sets the property $name to $value. * * @throws ezcBasePropertyNotFoundException if the property does not exist. + * @throws ezcBaseFileNotFoundException when setting the property with an invalid filename. * @param string $name * @param mixed $value - * @return void + * @ignore */ + public function __set( $name, $value ) /** - * Returns the property $name. + * Returns the value of property $value. * * @throws ezcBasePropertyNotFoundException if the property does not exist. * @param string $name - * @return mixed + * @param mixed $value + * @ignore */ + public function __get( $name ) +For documention how properties really work, please refer to +http://svn.ez.no/svn/ezcomponents/docs/guidelines/properties.txt. + Documenting \_\_set\_state -------------------------- If you have such a method for your class, it should be documented like this: :: @@ -364,12 +322,10 @@ @copyright ---------- -Required in either the page or class level dockblocks. It should be in the form +Required in either the page or class level dockblocks. It should be in the form:: - :: + @copyright Copyright (C) 2005, 2006 eZ systems as. All rights reserved. - "Copyright (C) 1999-2005 eZ systems as. All rights reserved." - @deprecated --------------- Required to use for everything that is deprecated. If a complete page or class @@ -396,7 +352,7 @@ @ignore ------------- -Use if needed +Use if needed. __set and __get method documentation always get this tag. @internal ------------- @@ -405,9 +361,9 @@ @license ------------ -Required for the documentation of all files. It should always read: :: +Required for the documentation of all files. It should always read:: - "http://ez.no/licenses/new_bsd New BSD License" + @license http://ez.no/licenses/new_bsd New BSD License @link ----------- @@ -477,29 +433,32 @@ -------- Required for all class variables. The only allowed syntax is: :: - /** - * Short description - * Longer description that can also span multiple lines, like - * this. - * @var type - */ - private $variableName; + /** + * Short description + * Longer description that can also span multiple lines, like + * this. + * @var type + */ + private $variableName; An example: :: - /** - * ezcPhpGenerator writes to the file with this name during execution. - * When [EMAIL PROTECTED] finish()} is called this file is moved to - * $resultFileName. - * @var string - */ - private $tmpFilename; + /** + * ezcPhpGenerator writes to the file with this name during execution. + * When [EMAIL PROTECTED] finish()} is called this file is moved to + * $resultFileName. + * @var string + */ + private $tmpFilename; @version ---------- -Required in all file descriptions. The file version should be autogenerated. +Required in all file and class descriptions. The values are auto generated, so +just use the format:: + @version //autogen// + .. Local Variables: Modified: docs/test_environment.txt =================================================================== --- docs/test_environment.txt 2006-08-29 08:46:19 UTC (rev 3413) +++ docs/test_environment.txt 2006-08-29 09:00:10 UTC (rev 3414) @@ -5,17 +5,19 @@ ============= - Make sure to use at least PHP 5.1 with PDO -- Make sure to use at least PHPUnit2 2.3.0 (stable or latest CVS) +- Make sure to use at least PHPUnit 3.0.0alpha15 Setup ===== -Run the following commands: :: +Run the following commands:: - $ pear install phpunit2 - $ cd ezcomponents/packages - $ Base/scripts/setup-env.sh - $ php UnitTest/trunk/src/runtests.php "mysql://test:[EMAIL PROTECTED]/ezc" + $ pear channel-discover http://pear.phpunit.de + $ pear install phpunit/phpunit2 + $ cd ezcomponents/ + $ ./scripts/setup-env.sh + $ cd trunk/ + $ php UnitTest/src/runtests.php -D "mysql://test:[EMAIL PROTECTED]/ezc" (Use a valid DSN for the last command.) @@ -32,7 +34,6 @@ some extra features (asserts etc.) that might be of use. Consult the API documentation for this package for more details. - .. Local Variables: -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
