web-dev-qa-db-ja.com

関数呼び出しを文書化する方法

WordPress PHPドキュメンテーション標準 を読んでも、add_action( 'foo', 'bar' );のような関数呼び出しを文書化する方法について言及しているところが見当たりません。

私は関数呼び出しを文書化するべきです、そして、もしそうなら、どのように？

documentationcoding-standards
5
henrywright

関数呼び出しを文書化するのではなく、関数定義を文書化します。関数は無制限に呼び出される可能性があるので、そうでしょうか。そのため、関数が呼び出されたときに文書化することは意味がありません。

あなたがその電話を文書化するのなら、おそらく後で覚えておきたいことをするか、あるいは他の次の開発者に知らせてください。しかし、通常、私は、それが起こるべきではないと言うでしょう - 完璧な世界では。

フックシステムは通常の呼び出しとは多少異なるため、混乱の原因となる可能性があります。しかし実際にはそうではありません、関数add_action()自体は文書化されているので、フックと使用される関数についてです。あなたの例を見てみましょう：

add_action( 'foo', 'bar' );

fooはフック、barは関数です。このためには、@ birgireが彼の答えでそれを示しているように、おそらくそれを試してみる必要があります。

私はあなたが関数を文書化する方法を知っていると思います、あなたは正しい文書をリンクしました。フックの文書化についても2つのセクションがあります。これは明らかにdo_action()とapply_filters()にのみ適用されます。

/* * 
 *要約。
 * 
 *説明。
 * 
 * @ xxx x 
 * 
 * @param type $ var説明。
 * @param array $ args {
 *このハッシュについての短い説明
 * 
 * @type type $ var説明。
 * @type type $ var説明。
 *} 
 * @param type $ var説明。
 */

/**このアクションはpath/to/filename.php */
に記載されています。

これは公式の部分です。

個人的にはこのようなものを追加するのが好きです。

/**
 * (Here is the official part)
 *
 * @hooked bar - 10
 */
do_action( 'foo' );

私はそれが幾分有用で情報提供的であると思うので、私はプロジェクトの最後の仕上げでこれをします。私はそれを思い付かなかった、しかしそれがどこから来たのか私に尋ねないでください、WCからのものかもしれません。さらに、それはおそらく良い習慣ではないことに注意したいと思います。ここのスキーマは

@hooked function_name - priority
4
Nicolai

そのような関数呼び出しのために特別なWordPressコア標準があるならば、それはこのファイルで使われることを期待するでしょう：

/wp-includes/default-filters.php

フック設定のマザーはを呼び出します。

そのファイルを読み飛ばすと、関数呼び出しごとに1行のコメント行しかないことがわかります。

// Slugs
add_filter( 'pre_term_slug', 'sanitize_title' );

いくつかの呼び出しはコメントの下にまとめられています：

// Mime types
add_filter( 'pre_post_mime_type', 'sanitize_mime_type' );
add_filter( 'post_mime_type', 'sanitize_mime_type' );

あるいはこのようにさえ：

// Format text area for display.
foreach ( array( 'term_description' ) as $filter ) {   
        add_filter( $filter, 'wptexturize'  );
        add_filter( $filter, 'convert_chars'    );
        add_filter( $filter, 'wpautop'          );
        add_filter( $filter, 'shortcode_unautop');
}

だから私はあなたにあなたのコードのために理にかなっているそしてそれをより読みやすくするのを助けることをするようにあなたに勧めます。

また、記述的コールバックを使用して読みやすさを向上させることもできます。例えば：

// BAD:
add_filter( 'the_title', 'wpse_11' );

// BETTER:
add_filter( 'the_title', 'wpse_remove_blacklisted_words' );
5
birgire