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
94
votes
2 answers
How to document magic (_call and _callStatic) methods for IDEs
After many happy years coding in notepad++ and sublime, I've been advised to give a PHP IDE a go. I'm trying out phpStorm and it seems nice. The code completion and documentation is a great feature but isn't working out for me when magic methods…
Rob Forrest
- 7,329
- 7
- 52
- 69
34
votes
4 answers
How do I customize NetBeans PHP auto DocBlock for methods and attributes?
After I create a method I use /** to generate the DocBlock. It auto fills the @param and @return for that function.
Example:
/**
*
* @param type $str
* @return type
*/
public function strlen($str){
return strlen($str);
}
How can I…
bxfckrclooo
- 598
- 1
- 4
- 8
30
votes
3 answers
phpStorm 7 update docblock
Is there a way to ask phpStorm to update the contents of a docblock? eg if I have the following code
//-------------------------------------------------------------------------
/**
* @param string $url
* @return $this
*/
public function…
Steve
- 3,601
- 4
- 34
- 41
23
votes
4 answers
Docblocks for Doctrine collections
Is there a standard way to document the expected class of entities inside a Collection in the docblock comment in a Doctrine project? Something like:
/**
* @var Collection
*/
protected $users;
Looks like PHPDoc is the de-facto standard for…
BenMorel
- 34,448
- 50
- 182
- 322
18
votes
3 answers
How to declare unlimited/variadic parameters in DocBlock?
Lets say I have a function (obviously a trivial example):
public function dot(){
return implode('.', func_get_args());
}
Now I know I could modify this to be
public function dot(array $items){
return implode('.', $array);
}
but with some…
Hailwood
- 89,623
- 107
- 270
- 423
15
votes
4 answers
Are there any PHP DocBlock parser tools available?
I would like to build some smaller scale but hightly customized documentation sites for a few projects. PhpDocumentor is pretty great but it is very heavy. I thought about trying to tweak the templates for that but after spending only a couple of…
Beau Simensen
- 4,558
- 3
- 38
- 55
13
votes
2 answers
When should I use NULL in PHPDoc type hints and docblocks?
I am confused about when to use the null as a type when describing variables with PHPDoc. Are type hints supposed to describe hopes and expectations for external callers to anticipate and comply with, or are they supposed to document all possible…
user1710673
- 139
- 1
- 3
9
votes
1 answer
How to collapse/expand all comment blocks in a file in PhpStorm?
In PhpStorm, what is a quick way to collapse or expand all the comment (doc) blocks in a file?
In the docs here it says:
Folding and expanding code blocks works for entire classes, inner and
anonymous classes, method bodies, import lists, comments,…
prograhammer
- 20,132
- 13
- 91
- 118
8
votes
6 answers
Most common docblock for Delphi and/or FreePascal code
I'm quite familiar with PHP dockblocks since it's been my job for the last 15+ years.
/**
* Description
*
* @tag bla bla
* @tag more bla bla
*/
What I'm trying to understand is if there is a standard like that for Delphi and/or…
Gustavo Carreno
- 9,499
- 13
- 45
- 76
7
votes
0 answers
Page-level docblocks and phpdocumentor templates
I'm having a really hard time to get phpDocumentor 2 working.
I have several files in procedural style, that must be documented. The only I found to do that is to use page-level docblocks, but it seems, that they don't work anymore correctly in…
Lorenz Meyer
- 19,166
- 22
- 75
- 121
6
votes
4 answers
generate annotated doctrine2 entites from db schema
Is it possible to generate Doctrine 2 entities, with the relevant docblock annotations, from an existing database schema?
waigani
- 3,570
- 5
- 46
- 71
6
votes
1 answer
What is the point of redundant php docblock tags like @static?
When using automatic php docblock generation in PhpStorm, I ended up with the @static annotation on a static method:
/**
* Reset the singleton instance, for the tests only
* @static
*/
public static function reset() {
self::$singletonInstance…
Matthieu Napoli
- 48,448
- 45
- 173
- 261
5
votes
1 answer
What does the annotation @template mean in PHP doc blocks?
I could see this PHPDoc block in the FakerPHP/Faker package, and I'm not aware what does @template mean? you can find it in the package's main branch on this line
/**
* @template T of Extension\Extension
*
* @param class-string $id
*
*…
Sherif Tarek
- 169
- 1
- 8
5
votes
3 answers
Do type declarations and type annotations obsolete or complement each other?
I've always used annotations to declare return type. For example:
/**
* @return SomeClass
*/
public function () { ... }
But now I see there's another way:
public function () : SomeClass { ... }
Question
Should I be choosing between these, using…
Alec
- 1,986
- 4
- 23
- 47
5
votes
0 answers
PhpStorm: ignore runtime / logic exceptions
In PhpStorm's settings in Editor/Inspections/PHP/PHPDoc/Missing @throw tag(s) there are two options which are selected by default:
Ignore Runtime Exceptions
Ignore Logic Exceptions
QUESTION: Why would I want to ignore these specific exceptions…
Tomasz Madeyski
- 10,742
- 3
- 50
- 62