CODEWITHSUNDEEP
phpphpdoc
Jeremy Harris
Jeremy Harris

Reputation: 24589

PHPDOC Examples Without Line Numbers

According to PHPDocumentor's documentation, to show an example it would be like this:

@example [location] [<start-line> [<number-of-lines>] ] [<description>]

This seems like a valid solution if code never changes but whenever you go and add new code to wherever the location is, your start-line potentially changes meaning you have to constantly be updating these various references.

Is there a better way to show an example of how to use a class method, within the DocBlock, without referencing an external current use example?

Here is what I am aiming for:

/**
 * @example This is how you use this method:
 *
 *     $baz = Foo::bar( array('bing' => $bing) ); 
 */

And then it shows up in the documentation as an example. Any ideas?

Upvotes: 2

Views: 1154

Answers (1)

ashnazg
ashnazg

Reputation: 6688

You can show a code example in the docblock itself by means of the "code" delimiter. So, for your original example:

/**
 * This is how you use this method:
 * <code>
 *     $baz = Foo::bar( array('bing' => $bing) ); 
 * </code>
 */

The manual page [1] for the @example tag shows both a "code" section in the docblock as well as @example pointers to lines in separate files.

[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.example.pkg.html

Upvotes: 1

Related Questions