PHPでデザインパターンを文書化する方法

Question

PHPでデザインパターンを使用するメソッドのドキュメントを作成しようとしています。一般に、メソッドはオブザーバ、インターセプトフィルタ、およびノー​​ティファクタを含みます。どのように私はこれをphp 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

あなたはコメントをあまりに多く書く傾向があります。コメントを最小限に抑えます。例えば。ファンクションがcheckboxで、パラメータが$nameの場合、チェックボックスの名前であることを文書化する必要はありません。明らかです。

このように@seeを使用する必要はありません。それは重複したコードです。変更された場合は、コメントも変更する必要があります。これは決して正しく行われることはないので、将来的には誤解を招く恐れがあります。それは避けるべきです。

いずれの場合でも、コードを調べるときにどの機能が使用されているかがわかります。

コメントを書く場合は、基本的なことを持つ小さな文章を使用します。誰が何をしますか（なぜではないか）。何かが作成された場合は、誰によって書いてください。 "要素を作成する文字列"だけではありません。どの要素？どのように文字列が何かを作成しますか？それは単なるデータです。単なるデータなので、多分もっと良いでしょう。

* @return string HTML 

関数が返すものは明確です。