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
1
vote
1 answer
ReflectionMethod->getDocComment() doesn't seem to work on PHP 5.5
I'm trying to make an interface from reflectionMethods for one of my classes, and I've got a problem where the method getDocComments() fails on my staging environment.
Here is the test code I use :
Marc Brillault
- 1,902
- 4
- 21
- 41
1
vote
0 answers
PHP Docblock for child using parent constructor?
What is the proper way to docblock this?
class B extends A
{
/**
* Constructor
*
* One of these, or???
* @uses A::__construct()
* @see A::__construct()
*
* @param int|null $id
* @param []|null $data
…
Katrina
- 1,922
- 2
- 24
- 42
1
vote
2 answers
Does PHP have a convention for describing Promise returns in function docblock
I just wrote a function like this
/**
* Send an asynchronous GET request
*
* @param string $url
* @param array $options
*
* @return \React\Promise\ExtendedPromiseInterface
*/
public function getAsync( $url, array $options…
Eugene
- 4,197
- 7
- 37
- 54
1
vote
1 answer
JSDoc: combining (optional) @param and @type for getter/setter function-properties
How can one use @param to hint the optional param for a function that is a property (this.selectedPage()) as well as use @type to hint its return type?
Take this for example (this.selectedPage() can receive a page by passing a parameter and return…
JDR
- 1,094
- 1
- 11
- 31
1
vote
1 answer
Remove [] square brackets from DocBlockr comment
I like the plugin DocBlockr for sublime text but I would like my comments to be a bit different.
The normal appearence:
And how I would like them to appear:
So the type, description without the [] square brackets is there anyway of doing this?…
SuperDJ
- 7,488
- 11
- 40
- 74
1
vote
1 answer
How would I write regex for getting the variable type from a variable comment?
I'm looking for a regex string to parse a property type from it's comment as below.
/**
* Identity
*
* @var integer
*/
protected $id;
I'm using the ReflectionProperty class to get the comment as a string as the var dump below:
string(55) "/**…
Paul Saunders
- 278
- 2
- 10
1
vote
0 answers
DocBlocks and Coda
I was just wondering if anybody was aware of any plug-ins that would make Coda use my php docBlocks..?
I have searched the programs itself and there doesn't seem to be the options for it.
I have also done a fairly thorough google search and came up…
G--
- 33
- 4
1
vote
1 answer
DocBlock documentation for instances of classes
Could you please give me some guidance on how I should document this piece of code with DocBloc documentation?
private $entityManager;
public function __construct($entityManager) {
parent::__construct();
$this->entityManager =…
luqo33
- 8,001
- 16
- 54
- 107
1
vote
1 answer
PHP mixed in getters and setters
Im using Php with doctrine and have a question regarding its setters/getters
Accordning to php.net mixed is
"mixed indicates that a parameter may accept multiple (but not necessarily all) types..." but why shall i use it when my $id is an int and…
Björn Gustafsson
- 378
- 2
- 7
1
vote
2 answers
phpDoc - no parameters or return value
Say I have the following class stub:
class Gentleman {
/** @var string */
protected $guestsName;
/**
* @param string $name The name of our esteemed guest
*/
public function __construct($name) {
$this->guestsName =…
Joe
- 15,669
- 4
- 48
- 83
1
vote
1 answer
Using the PHP docblocks @return tag is there a best practice for returning a boolean as an integer (i.e. 1 or 0)?
Is there a cleaner way to do this?
/**
* Will return either a 1 or 0
*
* @return int|boolean
*/
public function getExitCode()
{
return $this->exitCode;
}
It won't return a value cast as a boolean, it will be cast as an integer.
jcroll
- 6,875
- 9
- 52
- 66
1
vote
1 answer
How to use DocBlock comments in procedural code more effecient?
I am writing a script in the procedural PHP style, but still want to document everything the best I can. Thats why I use DocBlock comments. Being new to them, I wonder how to use them in the following scenario (code written especially for this…
Sven
- 12,997
- 27
- 90
- 148
1
vote
1 answer
reading / parsing Docblock in own file
Assuming I have a docblock like so :
* @since 0.0.1
* @subpackage my-package
* @todo too much
* @var int $myvar
* @version 0.0.99
or :
* Name: my app name
* URI: http://www.someurl.com
* Description: A Simple…
Obmerk Kronen
- 15,619
- 16
- 66
- 105
1
vote
2 answers
What tags should I use in PHP DocBlocks
Say for example I have my name as the author:
/**
* @author: Jacques Marais
*/
How can I include my website, my license and my copyright in my DocBlock? Which tags should I use?
Also what tags is the most common tags and how do I use them?
LightningBoltϟ
- 1,383
- 2
- 10
- 28
1
vote
1 answer
DocBlocks: Difference between @uses and @see
Fairly straightforward question - when writing docblocks, how should I determine whether I should be saying a structural element @uses another, and when should it tell people to @see the other element?
I've done a bit of Googling and a bit of SO…
Joe
- 15,669
- 4
- 48
- 83