Use DocBlox in Symfony2 for inspecting DocComment blocks

I was looking for a way to automatically generate some documentation, and because all the required information was already in the DocComment blocks. I downloaded the great documentation generator DocBlox (which is a PHP application by itself) and looked in it’s source code. Soon I found DocBlox’s Reflection classes which are able to parse a DocComment block. So I wanted to use these classes! Here is how you can do it:

Download the latest DocBlox zip file
Unzip the archive
Create the directory /vendor/docblox/src/DocBlox in your Symfony2 project
From the archive:
- copy /src/DocBlox/Reflection and it’s contents to the directory you have just created
- copy /src/markdown.php and the directory /src/markdown and it’s contents to /src/vendor/docblox/src
- Copy /LICENSE to /vendor/docblox

Now your directory structure should look like:

/vendor
  /docblox
    /src
      /DocBlox
        /Reflection/*
      /markdown/*
      /markdown.php
    /LICENSE

The license requires you to copy it with the code, even if you use part of it.

Now open /app/autoload.php and add the “DocBlox_” prefix to the autoloader:

$loader->registerPrefixes(array(
    'Twig_Extensions_' => __DIR__.'/../vendor/twig-extensions/lib',
    'Twig_'            => __DIR__.'/../vendor/twig/lib',
    // ...
    'DocBlox_'         => __DIR__.'/../vendor/docblox/src',
));

Also add this line to /app/autoload.php:

require_once __DIR__.'/../vendor/docblox/src/markdown.php';

This will enable you to use Markdown formatting in your DocBlocks.

The DocBlox reflection classes are now available in your project. I tested my configuration by creating the following action, which displays the type and description of it’s own return value:

   /**
     * Displays it's own "return" tag
     *
     * The "docBlox" action uses the DocBlox "DocBlock" reflection class
     *
     * @return Symfony\Component\HttpFoundation\Response The response
     */
    public function docBloxAction()
    {
        $reflectionMethod = new \ReflectionMethod($this, 'docBloxAction');
        $docBlock = new \DocBlox_Reflection_DocBlock($reflectionMethod);

        $returns = $docBlock->getTagsByName('return');
        if (!empty($returns)) {
            $return = reset($returns); // get the first "return" tag
            /* @var $return DocBlox_Reflection_DocBlock_Tag_Return */
            $type = $return->getType();
            $description = $return->getDescription();
            return new Response(sprintf('This method returns a %s which is %s', $type, lcfirst($description)));
        }

        return new Response('No return parameter was defined');
    }

As you can see, there is a limitation to the API of DocBlox: there is no getTag() method, only a getTags() and a getTagsByName() method, that both return an array. So you will have to reduce this to one tag yourself (for example by calling reset() on the array).

When this action is called, it renders the following text:

This method returns a Symfony\Component\HttpFoundation\Response which is the response

5 Responses to Use DocBlox in Symfony2 for inspecting DocComment blocks

# October 25, 2011 at 17:28

not sure how useful this is, I am sure it is, it is just that one cannot see it because even though it seems very interesting you set it up provide all instructions but failed to give a pretty use case or something we can reuse in our projects, how to use it, how we can generate docu for a regular sf2 project automatically, etc. If there are other tools, what are the advantages, if this can be used for other uses/libraries etc…

please install wp notify comments via email so that we can follow up, email me your reply as i will probably will not see your response here. Then I can subscribe.

Thanks
cordoval

# October 25, 2011 at 19:30

Thanks for your reply. I may not have been very clear about this: my use of DocBlox is not in the “official” way. I have taken part of the DocBlox codebase to inspect/reflect on my own DocComment blocks. Auto-generating documentation for your Symfony2 project is a whole different piece of cake; though I’m sure there are good resources available on the Internet.
matthiasnoback

# October 25, 2011 at 22:15

maybe, maybe not, it is a task to explore it now … open to opportunity
cordoval

# March 3, 2012 at 03:43

Like Symfony, it’s nice that you can use DocBlox components on their own. I was looking for a way to simply parse a raw DocComments return from the naitive Reflection classes, without re-inventing the wheel. Suprisingly, Doctrine doesn’t seem to seperate the parsing or tokenization in their Annotations implementation. Upon further searches, I stumbled upon DocBlox, and subsequently, your blog, thanks for posting.
Gator92

- # March 3, 2012 at 09:34
  
  Thanks! That was also a surprise to me, the Doctrine annotation reader is quite good, but only for returning objects, not for retrieving plain text values.
  Matthias Noback

PHP & Symfony

Use DocBlox in Symfony2 for inspecting DocComment blocks

5 Responses to Use DocBlox in Symfony2 for inspecting DocComment blocks

Leave a Reply Cancel reply

Matthias Noback

Recent posts