I would like to add some documentation comments for my (PHP) class and its functions in some standard format so that its easier for others to understand.
I will appriciate if you can give me an example that how you would write comments for following class and function? Thanks.
Info about class:
Classname Photos: it has some functions related to uploading the photo and displaying the photos. function names are upload(), display(), delete().
Info about upload function:
uploads the resizes and uploads the image and has few parameters as shown below.
<?php
class Photos extends CI_Controller
{
public function upload($file_name, $new_name, $new_width, $new_height, $directory)
{
...
...
returns true or false.
}
PHPDocumentor style is pretty standard and understood by most IDE's and documentation generators.
/**
* Photos
*
*
* @package CI
* @subpackage Controller
* @author YOUR NAME <YOUREMAIL@domain.com>
*/
class Photos extends CI_Controller
{
/**
*
* Uploads a file
*
* @param string $file_name description
* @param string $new_name description
* @param integer $new_width description
* @param integer $new_height description
* @param string $directory description
* @return boolean
*/
public function upload($file_name, $new_name, $new_width, $new_height, $directory)
{
}
}
You might want to look at doxygen. If you follow their syntax not only will you be able to auto generate documentation (not actually so useful), but the Zend IDE will give you code hints on auto completion (i.e. it will display the documentation when you start to type the function name).
/*! \brief My Photo Class
* Does some stuff with photos
*/
class Photos extends CI_Controller
{
/*! \brief Uploads a file
* \param $file_name The name of the file
* ...
* eturns A value indicating success
*/
public function upload($file_name, $new_name, $new_width, new_$height, $directory)
{
...
...
returns true or false.
}
}
/**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional'){
}
This will also be helpful for auto-complete in most known editors
I would use Natural Docs. The doc comments are easy to read right in the code thanks to human-friendly formatting:
<?php
/*
Class: Photos
Some functions related to uploading the photo and displaying the photos.
*/
class Photos extends CI_Controller
{
/*
Function: upload
Upload a photo to the server so that you can later <display> it.
Arguments:
file_name - name of the file
new_name - name of the file on the server
new_width - resize to this before uploading
new_height - resize to this before uploading
Returns:
true or false.
See Also:
<display>
<delete>
*/
public function upload($file_name, $new_name, $new_width, new_$height, $directory)
{
...
...
returns true or false.
}