<p dir="auto">Hi,<br>
Symfony source code is well commented but we can see a lot of different use of phpDoc. BTW, i think that would be a good idea to define how to write the phpDoc. (We can discuss here and update the symfony-docs)</p>
<p dir="auto">I think for exemple, this coding standard is the best actually:</p>
<p dir="auto"><a href="https://github.com/opensky/Symfony2-coding-standard">https://github.com/opensky/Symfony2-coding-standard</a></p>
<p dir="auto"><strong>I would like to have yours opinions before make a PR and fix all phpDoc.</strong></p>
<p dir="auto">I see some cases, i'll list them and can you say me if you're OK on each of them.</p>
<h1 dir="auto">A) Usage of inheritDoc</h1>
<div class="highlight highlight-text-html-php notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&lt;?php
/**
* @{inheritDoc} ---&gt; No
* {@inheritDoc} ---&gt; No
* {@inheritdoc}
* 
* (see http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html)
*/
public function myInheritedMethod() 
{
}"><pre class="notranslate"><span class="pl-ent">&lt;?php</span>
<span class="pl-c">/**</span>
<span class="pl-c">* @{inheritDoc} ---&gt; No</span>
<span class="pl-c">* {@inheritDoc} ---&gt; No</span>
<span class="pl-c">* {@inheritdoc}</span>
<span class="pl-c">* </span>
<span class="pl-c">* (see http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html)</span>
<span class="pl-c">*/</span>
<span class="pl-k">public</span> <span class="pl-k">function</span> <span class="pl-en">myInheritedMethod</span>() 
{
}</pre></div>
<p dir="auto">Adding too the <code class="notranslate">inheritDoc</code> on method where we use <code class="notranslate">see</code></p>
<div class="highlight highlight-text-html-php notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&lt;?php
/**
* {@inheritdoc}
*
* see \MyBundle\myInheritedMethod
*/
public function myInheritedMethod() 
{
}"><pre class="notranslate"><span class="pl-ent">&lt;?php</span>
<span class="pl-c">/**</span>
<span class="pl-c">* {@inheritdoc}</span>
<span class="pl-c">*</span>
<span class="pl-c">* see \MyBundle\myInheritedMethod</span>
<span class="pl-c">*/</span>
<span class="pl-k">public</span> <span class="pl-k">function</span> <span class="pl-en">myInheritedMethod</span>() 
{
}</pre></div>
<h1 dir="auto">B) Aligment</h1>
<div class="highlight highlight-text-html-php notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&lt;?php
/**
* ..... description ...
*
* align type of params, var names, and the comment
* ONLY ONE space between params, var names and comments
* 
* @param MyObject $a comment of A
* @param string   $b comment of b
*/
public function myMethod(MyObject $a, $b) 
{
}"><pre class="notranslate"><span class="pl-ent">&lt;?php</span>
<span class="pl-c">/**</span>
<span class="pl-c">* ..... description ...</span>
<span class="pl-c">*</span>
<span class="pl-c">* align type of params, var names, and the comment</span>
<span class="pl-c">* ONLY ONE space between params, var names and comments</span>
<span class="pl-c">* </span>
<span class="pl-c">* @param MyObject $a comment of A</span>
<span class="pl-c">* @param string   $b comment of b</span>
<span class="pl-c">*/</span>
<span class="pl-k">public</span> <span class="pl-k">function</span> <span class="pl-en">myMethod</span>(<span class="pl-smi"><span class="pl-smi">MyObject</span></span> <span class="pl-s1"><span class="pl-c1">$</span>a</span>, <span class="pl-s1"><span class="pl-c1">$</span>b</span>) 
{
}</pre></div>
<h1 dir="auto">C ) Return tag</h1>
<div class="highlight highlight-text-html-php notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&lt;?php
/**
* ..... description ...
*
*  skip a line between params and @return tag
* 
* @param MyObject $a comment of A
* @param string   $b comment of b
*
* @return boolean
*/
public function myMethod(MyObject $a, $b) 
{
    return true;
}"><pre class="notranslate"><span class="pl-ent">&lt;?php</span>
<span class="pl-c">/**</span>
<span class="pl-c">* ..... description ...</span>
<span class="pl-c">*</span>
<span class="pl-c">*  skip a line between params and @return tag</span>
<span class="pl-c">* </span>
<span class="pl-c">* @param MyObject $a comment of A</span>
<span class="pl-c">* @param string   $b comment of b</span>
<span class="pl-c">*</span>
<span class="pl-c">* @return boolean</span>
<span class="pl-c">*/</span>
<span class="pl-k">public</span> <span class="pl-k">function</span> <span class="pl-en">myMethod</span>(<span class="pl-smi"><span class="pl-smi">MyObject</span></span> <span class="pl-s1"><span class="pl-c1">$</span>a</span>, <span class="pl-s1"><span class="pl-c1">$</span>b</span>) 
{
    <span class="pl-k">return</span> <span class="pl-c1">true</span>;
}</pre></div>
<h1 dir="auto">D ) Type</h1>
<div class="highlight highlight-text-html-php notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="&lt;?php
/**
* ..... description ...
*
*  lowercase for type which are not object !
* 
* @param string $b comment of b
* @param String $b comment of b &lt;--- NO
*
* @return boolean
* @return Boolean &lt;---- No
*/
public function myMethod(MyObject $a, $b) 
{
    return true;
}"><pre class="notranslate"><span class="pl-ent">&lt;?php</span>
<span class="pl-c">/**</span>
<span class="pl-c">* ..... description ...</span>
<span class="pl-c">*</span>
<span class="pl-c">*  lowercase for type which are not object !</span>
<span class="pl-c">* </span>
<span class="pl-c">* @param string $b comment of b</span>
<span class="pl-c">* @param String $b comment of b &lt;--- NO</span>
<span class="pl-c">*</span>
<span class="pl-c">* @return boolean</span>
<span class="pl-c">* @return Boolean &lt;---- No</span>
<span class="pl-c">*/</span>
<span class="pl-k">public</span> <span class="pl-k">function</span> <span class="pl-en">myMethod</span>(<span class="pl-smi"><span class="pl-smi">MyObject</span></span> <span class="pl-s1"><span class="pl-c1">$</span>a</span>, <span class="pl-s1"><span class="pl-c1">$</span>b</span>) 
{
    <span class="pl-k">return</span> <span class="pl-c1">true</span>;
}</pre></div>
<p dir="auto">May have you other cases ?</p>
<p dir="auto">I can make a PR to rectify these cases on each file of symfony, but i would like to be sure you're OK before doing that :)</p>
<p dir="auto">There are several problems with the current way:</p>
<ul dir="auto">
<li>default logic is hard-coded in AbstractAuthenticationListener (can not be modified without copy/paste)</li>
<li>there are problems with XHR/automatic background requests that might change the redirect path (this is hard to customize at the moment)</li>
</ul>