Комментарии к классу и функциям PHP?
Я хотел бы добавить некоторые комментарии к документации для моего (PHP) класса и его функций в некотором стандартном формате, чтобы другим было легче понять.
Я буду признателен, если вы приведете мне пример того, как бы вы написали комментарии для следующего класса и функции? Спасибо.
Информация о классе:
Имя класса Фотографии: в нем есть некоторые функции, связанные с загрузкой фотографии и отображением фотографий. имена функций являются upload(), display(), delete().
Информация о функции загрузки:
Загружает изменения размеров и загружает изображение и имеет несколько параметров, как показано ниже.
<?php
class Photos extends CI_Controller
{
public function upload($file_name, $new_name, $new_width, $new_height, $directory)
{
...
...
returns true or false.
}
4 answers
Стиль phpDocumentor довольно стандартен и понятен большинству IDE и генераторов документации.
/**
* Photos
*
*
* @package CI
* @subpackage Controller
* @author YOUR NAME <[email protected]>
*/
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)
{
}
}
/**
* 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'){
}
Это также будет полезно для автозаполнения в большинстве известных редакторов
Возможно, вам захочется взглянуть на доксиген. Если вы будете следовать их синтаксису, вы не только сможете автоматически генерировать документацию (на самом деле это не так полезно), но и среда разработки Zend даст вам подсказки по коду для автоматического завершения (т. Е. Она отобразит документацию, когда вы начнете вводить имя функции).
/*! \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
* ...
* \returns A value indicating success
*/
public function upload($file_name, $new_name, $new_width, new_$height, $directory)
{
...
...
returns true or false.
}
}
Я бы использовал Естественные документы . Комментарии к документу легко читаются прямо в коде благодаря удобному для человека форматированию:
<?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.
}