In Symfony we can use the PHPDoc annotation, I wonder how we can reference a tutorial inside a PHPDoc block withing a Symfony project.
In the PHPDoc documentation example we see that they referenced this file phpDocumentor/phpDocumentor.pkg
:
/**
* Text with a normal @tutorial tag
* @tutorial phpDocumentor/phpDocumentor.pkg
*/
function element()
{
}
But how and where should I place those files inside of my Symfony project?
We should also know that the @package and @subpackage annotations are not used in Symfony.
Update
I want to use the tutorial tag to paste some example on how to use the method: the tutorial tag imports the content of the "linked" file into the description when generating the phpDoc. My problem is on how to link to this file in Symfony or where to put it, in which folder of the Symfony project.
Symfony works like any PHP framework and so its code is documented via PHPDoc, what you point out in the documentation links is more the "exceptions" that Symfony does in its usage of PHPDoc.
In PHPDoc, you can reference an external link with the @link
annotation, added to the doc block of a class, method of any documentable element.
Example:
<?php
/**
* Foo class.
*
* @see \ChildFoo
*
* @link http://helpful_related_resource.com/Foo
*/
class Foo
{
/**
* @var Bar
*
* @link http://helpful_related_resource.com/Foo#$bar
*/
private $bar;
/**
* Bar method.
*
* @link http://helpful_related_resource.com/Foo#getBar() Helpful resource
* @link http://helpful_related_resource.com/BarFactory Another helpful resource
*
* @return Bar
*/
public function getBar()
{
/**
* @link http://helpful_related_resource.com/Baz
*/
$baz = new Baz();
$this->bar->addBaz($baz);
return $this->bar;
}
}