Question

I have implemented entities within the Symfony2 framework that are annotated to be used by Doctrine. For example:

/*
 * class description
 *
 * @ORM\Entity(repositoryClass="Website\ContentBundle\Repository\ContentRepository")
 * @ORM\HasLifecycleCallbacks()
 * @ORM\InheritanceType("SINGLE_TABLE")
 * @ORM\DiscriminatorColumn(name="type", type="string")
 * @ORM\DiscriminatorMap({"article" = "Article"})
 * @ORM\Table(name="content",indexes={@ORM\index(name="id_UNIQUE",columns={"id"})})
 */
 class Content {
    /** 
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    private $id;

    ...
  }

When I run Doxygen on my source code, the documentation is not very readable. I have tried to define aliases for each @ORM* symbol; for example “ORM=ORM”, “Entity=Entity”, and so on. But this does not work. For the above mentioned class Doxygen returns

...
ORMEntity(repositoryClass="Website\ContentBundle\Repository\ContentRepository") ORM() ORM("SINGLE_TABLE") ORM(name="type", type="string") ORM({"article" = "Article", "picture_series" = "PictureSeries", "event" = "Event", "invitation" = "Invitation"}) ORMTable(name="content",indexes={ORM(name="id_UNIQUE",columns={"id"})}) 

With respect to method

/**
* sets the given id 
* 
* @param number $id
* @return \Website\ContentBundle\Entity\Content
*/
public function setId($id) {
    $this->id = $id;
    return $this; // fluent interface
}

Doxygen creates

setId ($ id)    
   sets the given id

Parameters:
    number  $id 

Returns:

Why does it not show the \Website\ContentBundle\Entity\Content after “Returns:”?

Maybe someone can give me a hint or a link on how to configure Doxygen such that it can handle the @ORM annotations appropriately.

THX in advance!

Answer 1

With respect to the question

Why does it not show the \Website\ContentBundle\Entity\Content after Returns:?

This is probably because doxygen commands start with a \, do doxygen thinks you are calling some commands which it does not recognise, and so presumably strips from the documentation and does nothing with.

You were on the right line with attempting to use the ALIASES configuration file option. However, instead of defining ORM=ORM try using ORM=\@ORM. I got your example source code to be documented by doxygen without any warnings by defining the following aliases:

ALIASES  = "ORM=\@ORM"  
ALIASES += "Entity=\\Entity"  
ALIASES += "InheritanceType=\\InheritanceType"  
ALIASES += "DiscriminatorColumn=\\DiscriminatorColumn"  
ALIASES += "DiscriminatorMap=\\DiscriminatorMap"  
ALIASES += "Table=\\Table"  
ALIASES += "Id=\\Id"  
ALIASES += "Column=\\Column"  
ALIASES += "GeneratedValue=\\GeneratedValue"  
ALIASES += "index=\\index"  
ALIASES += "HasLifecycleCallbacks=\\HasLifecycleCallbacks"  
ALIASES += "Repository=\\Repository"  
ALIASES += "ContentRepository=\\ContentRepository"  
ALIASES += "ContentBundle=\\ContentBundle"  
ALIASES += "Website=\\Website"  
ALIASES += "Content=\\Content"  

Here \\, \@ are actually doxygen commands for printing the backslash \ and @ characters respectively.

Note, however, that the @ORM... directives will all appear on the same line. I’m not sure how to avoid this (update: see my edit below). Does anyone else have any ideas?

Finally, as a side note, your documentation for $id should be

* @param $id number 

note the order of $id and number. See the documentation for \param.

Edit: An alternative way of doing this would be to wrap the Doctrine relavent parts in \verbatim and \endverbatim tags. This will preserve the line breaks in your class description which will be more readable.