News
	Latest
	Archive
	Community news

Articles
	C++
	Communities and Content
	Databases
	Editorials
	Emacs
	General
	HTML
	Java
	Notices
	PHP
	XML

Links
	Apache
	C++
	Database
	General
	HTML
	Java
	Javascript
	Linux
	Object oriented programming
	Open source
	Perl
	PHP
	Python
	Ruby
	SOAP
	XML
	Suggest a link

About
	Advertise on zez
	Contribute
	Contact us
	About zez

PHP class documentation

Author: Bård Farstad

Publishing date: 15.11.2000 15:47

More details

Every class should be grouped in to a module. This makes it easier to find related classes. The brief description of a class should only give a one sentence description of what the class does. The detailed class description is where you should describe how the class works and what you can do with it. You should only document what the class does, not how. The user of a class will be satisfied to know how to use it.

The detailed description field can contain example code and links to related classes. The code snippet below shows how you can use these features.

//!! Module Name
//! Short description.
/*!
  This is the detailed description..

  Here are some example code:
  \code
  $myObj = new MyClass();
  \endcode
  \sa MyOtherClass
*/

You can write code example between the \code and the \endcode tag. The \sa tag will make a link to other classes, and a "see also" field will appear in the class documentation.

Function description

Every function should have a small description. The description should be short and contain a description of the arguments. The return values should also be described. The code snippet below shows an example of a function description.

/*!
  This is a description of the function. The argument $value can be
  of the type MyObjet.
*/
function aSmallFunction( $value )
{

}

Variable description

Even variables should be described. Personally I don't describe every variable in the class. I only explain special variables or variables which are specially important. The code snippet below shows an example of a variable description.

/// This variable does something special. Note: foo bar.
var $myVar;

<< Previous page | 1 | < 2 > | 3 | 4 | Next page >> | Printer-friendly page |

Comment List

Topic:	Author:	Time:
subclasses	Geoff Caplan	16.03.2001 22:18
Love the tool. I like the markup style, which is less intrusive than the javadoc style to my way of thinking. The weakness, as I see it, compared to the main competition (www.phpdoc.de) is that ezphpdoc doesn't show the class hierarchy. If you get around to upgrading the script, perhaps you would consider adding this facility.
Good tool, need to discuss the specifics though	David Grinberg	21.02.2001 00:51
I think that after using this tool for a little while that it is an extremely good and powerful little tool. One that I will be using for all of my PHP documentation now. I also like the tutorial very easy to read and gets straight to the point. Although I would like to point out some problems that I had and tok me a while to figure out. 1. Cannot have an index class in a file called index.php. As the generator puts the class list in a file called index.html and puts the documentation for the index class into index.html (copies the name of the php file.) These two then overwrite one another. 2. Cannot have a space before the declaration of the class. class needs to be the first character on the line, otherwise the tool cannot find the name. 3. There is no description of how to insert the version in the tutorial. Just need to check out the source code in th example. Overall I love it. Keep up the good work!!
phpdoc	Ot Ratsaphong	28.11.2000 00:53
I am very impressed with this product. I especially like the ability to view the source code and the ability to switch back and forth b/w code and doco. Well Done!!! One thing I found missing in the article were some recommendations on what information to put in the documentation. The examples show fairly rudimentary documentation. We've got the tool to document our code, now let's see some examples of good documentation. BTW your coding style is a great example to follow.
RE: phpdoc examples	Paul Kenneth Egell-Johnsen	28.11.2000 18:51
Check out http://doc.ez.no for our nightly updated php classes. These are documented using what we consider good style. I will be the first, though, to admit that we haven't been very good at keeping it up, but rest assured, we will slowly get there.