Question

I use the word Notation because fabien potencier has its own generator but i can’t find what notation (or syntax if you will) it uses for the comments.

http://fabien.potencier.org/article/63/sami-yet-another-php-api-documentation-generator

Also, where can i find the comment notation to use the document generator?
Looks like PhpDocumentor but i cant be sure.

Does symfony use this generator?

Answer 1

Symfony 1.4 use phpDocumentor for (almost) sure.

I never tried Sami, but I guess it can be work on Symfony 1.4.

And about comment notation, I think there are almost the same for Sami, phpDoc, etc .. they all use DocBlock like:

/**
  * This is the short description for a DocBlock.
  *
  * This is the long description for a DocBlock. This text may contain
  * multiple lines and even some _markdown_.
  *
  * * Markdown style lists function too
  * * Just try this out once
  *
  * The section after the long description contains the tags; which provide
  * structured meta-data concerning the given element.
  *
  * @author  Mike van Riel <[e-mail]>
  *
  * @since 1.0
  *
  * @param int    $example  This is an example function/method parameter description.
  * @param string $example2 This is a second example.
  */

I took a random class in Symfony 2.0:

/**
 * Renders a Controller and returns the Response content.
 *
 * Note that this method generates an esi:include tag only when both the standalone
 * option is set to true and the request has ESI capability (@see Symfony\Component\HttpKernel\HttpCache\ESI).
 *
 * Available options:
 *
 *  * attributes: An array of request attributes (only when the first argument is a controller)
 *  * query: An array of request query parameters (only when the first argument is a controller)
 *  * ignore_errors: true to return an empty string in case of an error
 *  * alt: an alternative controller to execute in case of an error (can be a controller, a URI, or an array with the controller, the attributes, and the query arguments)
 *  * standalone: whether to generate an esi:include tag or not when ESI is supported
 *  * comment: a comment to add when returning an esi:include tag
 *
 * @param string $controller A controller name to execute (a string like BlogBundle:Post:index), or a relative URI
 * @param array  $options    An array of options
 *
 * @return string The Response content
 */

And an other one from symfony 1.4:

/**
 * Initializes this sfRequest.
 *
 * Available options:
 *
 *  * formats:           The list of supported format and their associated mime-types
 *  * path_info_key:     The path info key (default to PATH_INFO)
 *  * path_info_array:   The path info array (default to SERVER)
 *  * relative_url_root: The relative URL root
 *  * http_port:         The port to use for HTTP requests
 *  * https_port:        The port to use for HTTPS requests
 *
 * @param  sfEventDispatcher $dispatcher  An sfEventDispatcher instance
 * @param  array             $parameters  An associative array of initialization parameters
 * @param  array             $attributes  An associative array of initialization attributes
 * @param  array             $options     An associative array of options
 *
 * @return bool true, if initialization completes successfully, otherwise false
 *
 * @throws <b>sfInitializationException</b> If an error occurs while initializing this sfRequest
 *
 * @see sfRequest
 */