Как документировать шаблоны проектирования в PHP - PullRequest
Новая
       7

Как документировать шаблоны проектирования в PHP

2 голосов
/ 08 ноября 2011

Я пытаюсь написать документы для методов, которые используют шаблоны проектирования в PHP.Обычно метод содержит наблюдатели, перехватывающие фильтры и уведомители.Как я могу написать это в формате, который будет соответствовать документам php?Ниже приведен пример функции, для которой я пишу документацию.И, пожалуйста, скажите, выключено ли мое форматирование, чтобы я мог лучше писать документы. 

/**
     * Creates a checkbox input element with options passed too it.
     * 
     * @see PVHTML::getStandardAttributes()
     * @see PVHTML::getEventAttributes()
     * @see PVHTML::getStandardAttributes()
     * @see self::getFormAttributes()
     * 
     * @param string $name The name of the input being generated. Will be the input field's name
     * @param array $options Options than can be used to further distinguish the element. The options are
     *              the same values that will be passed through PVHTML::getStandardAttributes, PVHTML::getEventAttributes
     *              and get the self::getFormAttributes functions
     * @param array $css_options Options than can define how the CSS is styled around the form the div around the element.
     *              Options will be passed to PVHTML::getStandardAttributes() and PVHTML::getEventAttributes(). Have the option
     *              'disable_css' will disable the div surrouding the element.
     * 
     * @return string $element The string that creates the element
     * @access public
     */
    public static function checkbox($name, $options=array(), $css_options=array()) {

        if(self::_hasAdapter(get_class(), __FUNCTION__) )
            return self::_callAdapter(get_class(), __FUNCTION__, $name, $options, $css_options);

        $filtered = self::_applyFilter( get_class(), __FUNCTION__ ,  array('name'=>$name, 'options'=>$options, 'css_options'=>$css_options ), array('event'=>'args'));
        $name = $filtered['name'];
        $options = $filtered['options'];
        $css_options = $filtered['css_options'];

        $css_defaults=array('class'=>'form-checkbox');
        $css_options += $css_defaults;

        $input = self::input($name, 'checkbox', $options, $css_options);;
        self::_notify(get_class().'::'.__FUNCTION__, $input, $name, $options, $css_options);
        $input = self::_applyFilter( get_class(), __FUNCTION__ , $input , array('event'=>'return'));    

        return $input;
    }

1 Ответ

2 голосов
/ 08 ноября 2011

Вы склонны слишком много писать в комментариях, сводите комментарии к минимуму. Например. если функция называется checkbox, а параметр - $name - вам не нужно документировать, что это имя флажка. Это очевидно.

Вам не нужно использовать @ также. Это дублирующий код. Если он изменится, вам также нужно изменить комментарий. Это никогда не будет сделано правильно, поэтому приведет к вводящей в заблуждение документации в будущем. Этого следует избегать.

В любом случае вы видите, какие функции используются, если вы посмотрите на код.

Если вы пишете в комментариях, используйте небольшие предложения, в которых есть основные вещи: кто что делает (а не почему). Если что-то создано, напишите кем. Не просто «Строка, которая создает элемент». Какой элемент? Как строка создает что-то? Это просто данные. Как это просто данные, может быть, лучше 

 * @return string HTML

Так что понятно, что возвращает функция.

...