我应该如何记录函数调用？

时间：2015-02-24 作者：henrywright

正在读取WordPress PHP Documentation Standards, 我看不到任何地方提到如何记录函数调用，例如add_action( \'foo\', \'bar\' );

我应该记录函数调用吗？如果是，如何记录？

2 个回复

最合适的回答,由SO网友:Nicolai Grossherr 整理而成

您不记录函数调用，但记录函数定义。因为这个函数可以被无限次调用，对吗？因此，在调用函数时记录它们是没有意义的。

如果您记录了调用，那么可能是因为您做了一些您想稍后记住的事情，或者让其他后续开发人员知道。但通常，我会说，这不应该发生——在一个完美的世界里。

现在，钩子系统与正常调用有些不同，这可能是造成混淆的原因。但事实并非如此add_action() 它本身是有文档记录的，所以它是关于钩子和所使用的函数的。让我们看看您的示例：

add_action( \'foo\', \'bar\' );

在哪里foo 是钩子和bar 是函数。对于这一点，你可能必须像@birgire在他的回答中所展示的那样去做。

我假设您知道如何记录函数，您链接了正确的文档。在这里，您还可以找到关于记录挂钩的两个部分，这显然只适用于do_action() 和apply_filters().

4. Hooks (Actions and Filters); 示例：

    /**
     * Summary.
     *
     * Description.
     *
     * @since x.x.x
     *
     * @param type  $var Description.
     * @param array $args {
     *     Short description about this hash.
     *
     *     @type type $var Description.
     *     @type type $var Description.
     * }
     * @param type  $var Description.
     */

4.1 Duplicate Hooks; 示例：

/** This action is documented in path/to/filename.php */

这是官方部分。

个人喜欢添加以下内容：

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

我是在项目收尾时做这件事的，因为我觉得它有一定的帮助和信息。我没有想到这一点，但不要问我它来自哪里，可能来自WC。此外，我想指出，这可能不是一个好的做法。这里的模式是

@hooked function_name - priority

SO网友:birgire

如果有一个特殊的WordPress核心标准，那么对于此类函数调用，人们会期望在这个文件中使用它：

/wp-includes/default-filters.php

钩子之母设置调用。

浏览该文件，我们发现每个函数调用最多只有一行注释：

// 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\' );

结束

小码农CODE

我应该如何记录函数调用？

相关推荐

Buddypress Full documentation