Documentation

XML, Perl, Python, and other languages can be discussed here, even if it isn't PHP (We might forgive you).

Moderator: General Moderators

Post Reply
shivam0101
Forum Contributor
Posts: 197
Joined: Sat Jun 09, 2007 12:09 am

Documentation

Post 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?
User avatar
xpgeek
Forum Contributor
Posts: 146
Joined: Mon May 22, 2006 1:45 am
Location: Kyiv, Ukraine
Contact:

Post 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
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Re: Documentation

Post 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 :)
Post Reply