美しいコードコメントブロックのデザイン：ギャラリー、記事、設定

Question

私はいつも何が起きているのかをすぐに理解できるように自分のコードを大量に書いています。だから、私はそこにギャラリーやコメントのコレクションがあるかどうか疑問に思うことが多い。すべてのリンクまたは一般的な設定ですか？

ここに私がよく使うカップルがあります（PHPで）。ファイルの先頭に

：

// =======================================================================// 
// ! A description of what the following functions have in common   //   
// =======================================================================// 

私はいつも一番時間「コメントブロック」ので、このトピックに関する検索をしました：関数のグループにラベルを付けるために使用さ

// ******************************* INFORMATION ***************************// 

// ***********************************************************************// 
// 
// ** NAME - A description of what the file does. 
// ** 
// ** @author name <name@name.com> 
// ** @date date 
// ** @access private 
// ** @param  
// ** @return if a class what object is returned 
//  
// ***********************************************************************// 

// ********************************** START ******************************// 

または「コードコメント」は、通常、ブログのコメントシステムを書くときに何かを返します:)

Answer 1

これは@jcomeau_ictxで提案されているように主観的ですが、phpDocumentor（またはphpdocまたはphpd） ocu）。私はあなたがそれを見ることを強く勧めます。資料はhttp://manual.phpdoc.org/HTMLframesConverter/default/にあります。

構文はあなたのものと少し異なります。これはJavadocに似ています。例えば

：

/** 
* Sample File 3, phpDocumentor Quickstart 
* 
* This file demonstrates the use of the @name tag 
* @author Greg Beaver <cellog@php.net> 
* @version 1.0 
* @package sample 
*/ 

は、サイトに表示するためのいくつかの例があります。

http://www.google.com/codesearchをチェックして、コメントの可能性が高い特定の単語（たとえばfunctionまたはclass）を含むPHPファイルを検索することもできます。