Как использовать phpDocumentor для CodeIgniter

Я создал довольно обширное веб-приложение и просматривал руководство по стилю для CodeIgniter (CI), чтобы узнать, как делать комментарии. У него есть такие вещи для классов и методов:

/** 
* Super Class 
* 
* @package Package Name 
* @subpackage Subpackage 
* @category Category 
* @author Author Name 
* @link http://example.com 
*/ 

class Super_class {}

/** 
* Encodes string for use in XML 
* 
* @access public 
* @param string 
* @return string 
*/ 

function xml_encode($str){}

Это нормально, но тогда я не знаю, что заполнять для этих опций. У меня действительно нет @package, у меня есть только несколько моделей и контроллеров. В Java я мог бы использовать пакеты для безопасности, но не в CI, это просто MVC. У меня всегда есть такие вещи, как, например, project_mode, проекты (контроллер) и add_project_view.php.

Также какой формат для @category? В документах phpDocumentor говорится: «Тег @category используется для организации групп пакетов вместе». Опять же, никаких пакетов!

Во-вторых, как быть с параметрами в методах? Иногда у меня есть две строки и массив или целое число и массив. Каков формат @param?

Спасибо,


php documentation codeigniter phpdoc
person Adamantus    schedule 26.09.2012    source источник

Ответы (2)


arrow_upward
3
arrow_downward

Пакет, подпакет и категория предназначены для лучшего логического структурирования кода. Это не обязательно должно быть там для каждого файла проекта/кода, который у вас есть.

С другой стороны, параметры в методах очень полезно определять, потому что нам нужно знать, что они собой представляют при чтении документации, потому что нам нужно передавать их при вызове этих методов в нашем коде.

Образец будет таким:

/**
 * Sample function
 * @param string $param1 name of person
 * @param integer $param2 age of person 
 * @return string 
 */
function person($name, $age)
{
    return "$name is $age years old";
}
person raidenace    schedule 26.09.2012
comment
Спасибо за помощь в параметрах. - person Adamantus; 27.09.2012

arrow_upward
0
arrow_downward

@package можно использовать только для документирования процедурных страниц или классов.

Пакеты используются, чтобы помочь вам логически сгруппировать связанные элементы. Вы пишете классы для группировки связанных функций и данных, а phpDocumentor представляет содержимое файлов (функций, определений и включений) в виде «Процедурных страниц». Пакет используется для группировки классов и процедурных страниц таким же образом, как каталог группирует вместе связанные файлы.

Вы можете найти ответы на свои вопросы и многое другое в руководстве по phpDocumentor здесь

person Jamshid Hashimi    schedule 26.09.2012
comment
(Я ссылался на руководство в своем исходном посте.) По объяснению здесь я бы сказал, что пример пакета будет моделями или контроллерами? - person Adamantus; 27.09.2012
comment
Да, хорошей базовой структурой пакета для приложения MVC будут модели, контроллеры и представления. Тег группировки пакетов предназначен только для логической группировки вещей в зависимости от того, как вы хотите, чтобы они были представлены в ваших документах. Они не имеют никакого отношения к выполнению кода, если только вы не решите выравнивать элементы пакета на основе этого. Этот тег предшествовал пространству имен, которое было добавлено в PHP 5.3, поэтому это был единственный способ организации ваших документов каким-либо образом. - person ashnazg; 27.09.2012