Question

I am trying to write documents for methods that use design patterns in PHP. Generally a method contains observers, intercepting filters and notifiers. How can I write this into a format that will fit the php docs? An example of a function that I am writing documentation for is below. And please tell if my formatting is off so I can get better at writing docs.

/**
     * 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;
    }

Answer 1

You have a tendency to write too much in comments, keep comments to a minimum. E.g. if the function is called checkbox and the parameter is $name – you don’t need to document that it’s the name of the checkbox. It’s obvious.

You don’t need to use @see that way as well. That’s duplicate code. If it changes you need to change the comment as well. This will never be done correctly, so will result in misleading documentation in the future. That should be avoided.

In any case you see which functions are used if you look into the code.

If you write in comments, use small sentences that have the basic things: Who does what (and not why). If something is created, write by whom. Not just “The string that creates the element”. What element? How does the string create something? It’s just data. As it’s just data, maybe better

 * @return string HTML

So it’s clear what the function returns.