How to doc a variable number of parameters - php

How do I doc a variable number of parameters? I am writing an application in PHP and JavaScript. Currently I have (in JavaScript):
/**
* Description
* #param {String} description
*/
function fn()
{
// arguments holds all strings.
}
So, how do I doc n-number of string params?

E.g. PhpDocumentor suggests using an ellipsis
/**
* Example of unlimited parameters.
* Returns a formatted var_dump for debugging purposes
* (since the recurrences of $v are not listed in the actual function signature in the code,
* you may wish to highlight they are "optional" in their description)
* #param string $s string to display
* #param mixed $v variable to display with var_dump()
* #param mixed $v,... unlimited OPTIONAL number of additional variables to display with var_dump()
*/
function fancy_debug($s,$v)
{

Related

Would it make a difference to PHPdoc if I close my tags with colon (example)?

I always use colons in my phpdoc blocs. For example, instead of:
/** Some comment
*
*#private
*
*#param string $sTable The name of the table
*#return bool True otherwise void
*#example className->tableExists($sTable);
*#since date
*/
Instead of the above, I use the following style:
/** Some comment
*
* #private
*
* #param : string $sTable The name of the table
* #return : bool True otherwise void
* #example : className->tableExists($sTable);
* #since : date
*/
You see, I prefer to divide the tags and description with colons. It's easier to read and has more style. But I wonder if this makes any difference for PHPdoc parsing the docbloc at all?
To PHPDocumentor it makes quite a difference. Testing shows the following
/**
* Test constructor.
* #param : string $var testvar
*
*/
gets documented to:
Where
/**
* Test constructor.
* #param string $var testvar
*
*/
outputs
It is ofcourse somewhat logical that it is that way, as it is a syntax error. If you want to make the docblock look nice, you can align the values with spaces.
/** Some comment
*
*#private
*
*#param string $sTable The name of the table
*#return bool|void True otherwise void
*#example className->tableExists($sTable);
*#since date
*/
I'm not sure about PHPDoc itself, but it would make a difference to some IDEs. I tried this in PHPStorm and while #param and #var were unaffected, #return failed out.
I would be cautious using a non-standard format.

PhpDocs: Link to another method in "#deprecated" tag's description?

Is it possible to link to another method/class/property/etc. inside my project inline inside the #deprecated tag? Like this:
/**
* Method description
* #deprecated 1.0 Reason for deprecation, use {#link newMethod()} instead!
* #param string $str
* #param string|null $str2
* #return bool
*/
public function method($str, $str2) {
// TODO: Code...
}
...
?
According to PHPdoc.org, you could use the #see tag for that.
/**
* #see http://example.com/my/bar Documentation of Foo.
* #see MyClass::$items For the property whose items are counted.
* #see MyClass::setItems() To set the items for this collection.
*
* #return integer Indicates the number of items.
*/
function count()
{
<...>
}
Also, PHPdoc.org recommends to use #see in case of a #deprecated method:
It is RECOMMENDED (but not required) to provide an additional description stating why the associated element is deprecated. If it is superceded by another method it is RECOMMENDED to add a #see tag in the same PHPDoc pointing to the new element.
But #see is not always required, for example "Link to another method in #param tag's description?"

Aptana 3 ScriptDoc - #Return not working in Code Assist

I found this question that had been answered, but it didn't solve my problem:
Aptana Scriptdoc doesn't show up in Code Assist
Using the PHP equivalent of their example...
/**
* Gets the current foo
* #param {String} $fooId The unique identifier for the foo.
* #return {Object} Returns the current foo.
*/
public function getFoo($fooId) {
return $bar[$fooId];
}
However, the documenation provided looks like this (extra ending braces included):
getFoo($fooId)
Gets the current foo
#param String $fooId The unique identifier for the foo.
#return Object}
Resolved return types: Object}
Please let me know what I'm doing wrong.
Thanks!
The #return type should not be wrapped with curly brackets.
Your doc should look like this:
/**
* Gets the current foo
* #param String $fooId The unique identifier for the foo.
* #return Object Returns the current foo.
*/
public function getFoo($fooId) {
return $bar[$fooId];
}
The parsing of the return type follows the PHPDoc #return rules.
This also means you can have a mixed return type, which will give you code-assist suggestions from multiple types.
For example:
/**
* #return MyClass|PDO doc doc doc
*/
Cheers

#param tag alignment in php code sniffer

I am using php code sniffer for a function, i want to add #param tag but it is giving me alignment error of first and second param.
/**
* for generating thumbnail
*
* #param int $minSize an integer to size of thumbnail
* #param string $sourceUrl the string to source url
*
* #return int the integer
*/
function imgThumbs($minSize, $sourceUrl)
{
}
please suggest, what is the problem why it is not showing , first and second are not aligned.
Expected 1 space after the longest variable name
In your code the longest variable name $sourceUrl is followed by 2 spaces.
Edit: Here is how it should work (at least this error should disappear). I used dots for spaces at the important places.
/**
* for generating thumbnail
*
* #param.int....$minSize...an integer to size of thumbnail
* #param.string.$sourceUrl.the string to source url
*
* #return int the integer
*/

How to document an accessor/mutator method in phpDoc/javaDoc?

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.

Categories