如何在phpDoc / javaDoc中记录访问器/ mutator方法？ [英] How to document an accessor/mutator method in phpDoc/javaDoc?

问题描述

根据传递给它的参数，给出一个表现为mutator或访问器的函数，如下所示：

  /在PHP中，您可以将任意数量的参数传递给函数... 
 function cache（$ cacheName）{
 $ arguments = func_get_args（）; 
 
 if（count（$ arguments）> = 2）{//两个参数传递。突变基因。 
 
 $ value = $ arguments [1]; //使用第二个作为值
 $ this-> cache [$ cacheName] = $ value; // * change *存储值
 
} else {// 1个参数传递，ACCESSOR 
 return $ this-> cache [$ cacheName]; // * get *存储值
} 
} 
 
缓存（'foo'，'bar'）; //没有返回
 cache（'foo'）//'bar'returned 
  

您是否在PHPDoc或类似的自动化文档创建者中记录？我原来刚刚这样写：

  / ** 
 * Blah blah blah，你可以使用这个一个mutator和一个访问器：
 *作为访问者：
 * @param $ cacheName变量的名称GET 
 * @return字符串值
 * 
 *作为mutator：
 * @param $ cacheName变量名为SET 
 * @param $ value要设置的值
 * @return void 
 * / 
  

但是，当这是通过phpDoc运行时，它抱怨因为有2个返回标签，第一个

有没有办法解决这个问题？

解决方案

你发现，你不能记录一个功能的两个不同的签名。但是，如果您使用 phpDocumentor - ，则可以执行以下操作：可选功能参数和多个可能的返回类型：

  / ** 
 * Blah blah blah，您可以将其用作访问器和变异器，例如
 *< code> cache（'name'）//获取缓存值< / code> 
 *和
 *< code> cache（'name'，'value'）//设置新的缓存值< / code> ;. 
 * 
 * @param string $ cacheName GET的变量名称| SET 
 * @param string $ value可选新值
 * 
 * @return string | $ cacheName的void值，或者在mutator的情况下，为了清楚起见，void 
 * / 
  

我也会包括使用示例。

Given a function which behaves as either a mutator or accessor depending on the arguments passed to it, like this:

// in PHP, you can pass any number of arguments to a function...
function cache($cacheName) {
    $arguments = func_get_args();

    if (count($arguments) >= 2) {   // two arguments passed. MUTATOR.

        $value = $arguments[1];             // use the second as the value
        $this->cache[$cacheName] = $value;  // *change* the stored value

    } else {    // 1 argument passed, ACCESSOR
        return $this->cache[$cacheName];  // *get* the stored value
    }
}

cache('foo', 'bar');  // nothing returned
cache('foo')          // 'bar' returned

How do you document this in PHPDoc or a similar automated documentation creator? I had originally just written it like this:

/**
 *  Blah blah blah, you can use this as both a mutator and an accessor:
 *    As an accessor:
 *    @param   $cacheName   name of the variable to GET
 *    @return  string       the value...
 *
 *    As a mutator:
 *    @param   $cacheName   name of the variable to SET
 *    @param   $value       the value to set
 *    @return  void
 */

However, when this is run through phpDoc, it complains because there are 2 return tags, and the first @param $cacheName description is overwritten by the second.

Is there a way around this?

解决方案

as you found out, you cannot document 2 different signatures of a single function. what you can do, however - if you use phpDocumentor -, is to document optional function parameters and multiple possible return types:

/**
 * Blah blah blah, you can use this as both an accessor and a mutator, e.g.
 * <code>cache('name') // get cache value</code>
 *   and
 * <code>cache('name', 'value') // set new cache value</code>.
 *
 * @param   string  $cacheName  name of the variable to GET|SET
 * @param   string  $value      optional new value
 *
 * @return  string|void value of $cacheName or, in case of mutator, void
 */

for clarity, i would also include the usage example.

这篇关于如何在phpDoc / javaDoc中记录访问器/ mutator方法？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！