Page 1 of 1

Documentation

Posted: Tue Aug 28, 2007 3:44 am
by shivam0101
This is how i am writing comments.

/****************************************************************************************************
Name : Login
Description : Checks for existence of username and password in clients table.

Paramenters : $username, $password
On Success : redirect to mypage.php
On Failure : return errors
*****************************************************************************************************/
should there be any thing which has to be included?

Posted: Tue Aug 28, 2007 4:18 am
by xpgeek
You can use one of existing Programming styles:
I recommended PEAR programming style,
but you can see another styles here wiki Programming style

Re: Documentation

Posted: Tue Aug 28, 2007 10:10 am
by Chris Corbyn
shivam0101 wrote:This is how i am writing comments.

/****************************************************************************************************
Name : Login
Description : Checks for existence of username and password in clients table.

Paramenters : $username, $password
On Success : redirect to mypage.php
On Failure : return errors
*****************************************************************************************************/
should there be any thing which has to be included?
A documenting tool won't parse that itself. There is a standard way to write documenting comments in PHP and in Java (and other languages).

Open the comment with /** (two asterisks). End the comment with */ (one asterisk).

Code: Select all

/**
 * Brief summary of method/property.
 * More in-depth description of method/property,
 * possibly even giving some code examples:
 * $foo->bar('xyz');
 * @param string Summary of parameter 1
 * @param int Summary of parameter 2
 * @return boolean
 */
public function bar($a, $b) {
  return true;
}
Each successive line starts with a single * indented to the same level as the one above it. The summary should ideally be on one line and ends when a dot (.) is encountered.
The description can span as many lines as needed until a @param, @return, @deprecated, @throws etc tag is seen.
The @param syntax is as follows:

@param datatype Details

@return specifies the data type that is returned.

This is for a specific tool, but it should still give you a good insight:
http://manual.phpdoc.org/HTMLSmartyConv ... o.pkg.html

You'll notice loads of people write comments this way because it's practically a universal standard and most documenting tools expect comments to be written this way :)