A DocBlock is a specially formatted PHP comment which allows external document generators to generate documentation of APIs and helps some IDEs to interpret variable types, provide improved code completion, type hinting and debugging.
Questions tagged [docblocks]
104 questions
0
votes
1 answer
Using DocBlocks - how to indicate that a function returns a value only in some conditions?
I have this function:
public function createController()
{
$valid_controller = class_exists($this->controllerClass)
&& in_array("BaseController", class_parents($this->controllerClass));
if($valid_controller)
{
…
Michael Haddad
- 4,085
- 7
- 42
- 82
0
votes
2 answers
Using DocBlocks on PHP, Should I use @throws when I do not handle errors with execpetion?
I have a class for handling errors, and it is not using the try-throw-catch mechanism.
When I am commenting code that uses that class, should I use the the @throws tag even though I do not actually throwing anything?
EDIT (try to make my question…
Michael Haddad
- 4,085
- 7
- 42
- 82
0
votes
0 answers
How to prevent spam in docblock comments?
I often publish PHP code on GitHub and in my code I use docblock comments that contain, among other things, my email address like this:
/**
* @author Foo Bar
*/
I fear that this is going to attract spammers and I am looking…
Rudloff
- 119
- 7
0
votes
0 answers
Git ignore inline docblock
When using factory-like patterns, PhpStorm only recognises classes when docblock comment is used. Example:
/** @var \Some\Thing $thing */
$thing = $this->factory('some/thing');
$thing->doSomething();
Without the @var declaration, PhpStorm doesn't…
Jesse
- 1
0
votes
2 answers
Is there a way to "reuse" a PHP DocBlock?
I currently have code like this:
/**
* blah blah blah thing1
*
* @return string a thing1
*/
function thing1() {
//
}
/**
* blah blah blah thing2
*
* @return string a thing2
*/
function thing2() {
//
}
//dozens more with the same…
Ryan
- 5,883
- 13
- 56
- 93
0
votes
1 answer
Proper PHPDoc for switch statement with object return value
If you could be so kind to take a look at the project I'm working on at this line ( the function api() ).
https://github.com/wtfzdotnet/php-tmdb-api/blob/develop/lib/Tmdb/Client.php#L79
What is the correct way here for IDE's to actually auto…
wtfzdotnet
- 1,022
- 8
- 11
0
votes
2 answers
Parse docblocks of function calls, not function definitions?
I'm trying to get docblocks preceding certain function calls in a PHP file. The difference to the usual approach is that I'm not trying to parse docblocks of function definitions.
Example file:
random…
oschloebe
- 386
- 1
- 2
- 16
0
votes
1 answer
Sublime Text 2 Comment Format Support
Does Sublime Text 2 can support the comment like this ?
/** @param @return */
Does any plugin can do it in PHP or JS or CSS?
(I do install the plugin :DocBlockr already.
But it can't work in windows7 now)
Additional post on segmentfault.com (in…
Amoi
- 1
- 3
0
votes
2 answers
Properly Label Author and Project name in PHP Files?
I simply wanted to know what is the most accepted way to credit yourself and describe the overall package in (preferably) the beginning of the document so other individuals viewing the code have a reference?
I would like to know the answer because…
established
- 3
- 1
0
votes
1 answer
Automatic timestamp during Docblocker creation?
Is there a method to create a live template which would give out the current timestamp by maybe pressing 't' + TAB in phpStorm:
I want to do this in the creation of the DocBlocks as I like to keep a track of the changes in the code, for Ex :
/**
*…
Sankalp Singha
- 4,461
- 5
- 39
- 58
0
votes
1 answer
php storm customize docblock
Is there a way to customize php storm's way of generating the docblocks ?
By default, I would like to have unknown type vars considered as strings.
This is the default way of generating docblock
(using php storm 4.01)
/**
* @param $name
*/
private…
ling
- 9,545
- 4
- 52
- 49
0
votes
1 answer
PHP "namespaced" docblock tags?
I've seen this used (example from Doctrine2) in a lot of libraries that have code which works with comments:
Ivan Pintar
- 1,861
- 1
- 15
- 27
0
votes
1 answer
Is is still proper to include the @param varname in a PHP docblock?
According to wikipedia the format for @param docblock parameters is type [$varname] description where $varname is optional. This seems to be backed by the phpDocumentor project which states:
@param datatype $paramname description
@param…
Xeoncross
- 55,620
- 80
- 262
- 364
-1
votes
1 answer
nodejs router docblock comment
I am writing below docblock for one of my app routers. Is it right?
also, tell me the meaning of each line as I don't know exactly.
/**
* Router serving Activity log page.
* @name get/activity_log
* @function
* @memberof…
saurabh r
- 1
- 2