StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

PO
primarykey
Id
1936421
data
AcceptedAnswerId
0
AnswerCount
0
ClosedDate
CommentCount
7
CommunityOwnedDate
CreationDate
2009-12-20T17:33:54.167
FavoriteCount
0
LastActivityDate
2014-03-14T10:05:20.003
LastEditDate
2014-03-14T10:05:20.003
LastEditorUserId
71480
OwnerUserId
138475
ParentId
1936376
PostTypeId
2
Score
42
ViewCount
0
LastEditorDisplayName
text
Body
I think <a href="http://pear.php.net/manual/en/package.php.php-codesniffer.php" rel="noreferrer"><code>PHP_Codesniffer</code></a> can indicate when there is no docblock -- see the examples of reports on <a href="http://pear.php.net/manual/en/package.php.php-codesniffer.usage.php" rel="noreferrer">this page</a> (quoting one of those) : <pre><code>-------------------------------------------------------------------------------- FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S) -------------------------------------------------------------------------------- 2 | ERROR | Missing file doc comment 20 | ERROR | PHP keywords must be lowercase; expected "false" but found | | "FALSE" 47 | ERROR | Line not indented correctly; expected 4 spaces but found 1 47 | WARNING | Equals sign not aligned with surrounding assignments 51 | ERROR | Missing function doc comment 88 | ERROR | Line not indented correctly; expected 9 spaces but found 6 -------------------------------------------------------------------------------- </code></pre> I suppose you could use PHP_Codesniffer to at least get a list of all files/classes/methods that don't have a documentation; from what I remember, it can generate XML as output, which would be easier to parse using some automated tool -- that could be the first step of some docblock-generator ;-) Also, if you are using <a href="http://www.phpdoc.org/" rel="noreferrer">phpDocumentor</a> to generate the documentation, can this one not report errors for missing blocks ? After a couple of tests, it can -- for instance, running it on a class-file with not much documentation, with the <code>--undocumentedelements</code> option, such as this : <pre><code>phpdoc --filename MyClass.php --target doc --undocumentedelements </code></pre> Gives this in the middle of the output : <pre><code>Reading file /home/squale/developpement/tests/temp/test-phpdoc/MyClass.php -- Parsing file WARNING in MyClass.php on line 2: Class "MyClass" has no Class-level DocBlock. WARNING in MyClass.php on line 2: no @package tag was used in a DocBlock for class MyClass WARNING in MyClass.php on line 5: Method "__construct" has no method-level DocBlock. WARNING in MyClass.php on line 16: File "/home/squale/developpement/tests/temp/test-phpdoc/MyClass.php" has no page-level DocBlock, use @package in the first DocBlock to create one done </code></pre> But, here, too, even if it's useful as a reporting tool, it's not that helpful when it comes to generating the missing docblocks... Now, I don't know of any tool that will pre-generate the missing docblocks for you : I generally use PHP_Codesniffer and/or phpDocumentor in my continuous integration mecanism, it reports missing docblocks, and, then, each developper adds what is missing, from his IDE... ... Which works pretty fine : there is generally not more than a couple of missing docblocks every day, so the task can be done by hand (and Eclipse PDT provides a feature to pre-generate the docblock for a method, when you are editing a specific file/method). Appart from that, I don't really know any fully-automated tool to generate docblocks... But I'm pretty sure we could manage to create an interesting tool, using either : <ul> <li><a href="http://fr2.php.net/reflection" rel="noreferrer">The Reflection API</a></li> <li><a href="http://fr2.php.net/manual/en/function.token-get-all.php" rel="noreferrer"><code>token_get_all</code></a> to parse the source of a PHP file.</li> </ul> After a bit more searching, though, I found this blog-post (it's in french -- maybe some people here will be able to understand) : <a href="http://fxnion.free.fr/articles/phpdoc-tags-php-beautifier.php" rel="noreferrer">Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier</a>. Possible translation of the title : "Automatically adding phpDoc tags, using PHP_Beautifier" The idea is actually not bad : <ul> <li>The <a href="http://pear.php.net/package/PHP_Beautifier" rel="noreferrer"><code>PHP_Beautifier</code></a> tool is pretty nice and powerful, when it comes to formating some PHP code that's not well formated <ul> <li>I've used it many times for code that I couldn't even read ^^</li> </ul></li> <li>And it can be extended, using what it calls "filters". <ul> <li>see <a href="http://beautifyphp.sourceforge.net/docs/PHP_Beautifier/Filter/PHP_Beautifier_Filter.html" rel="noreferrer"><code>PHP_Beautifier_Filter</code></a> for a list of provided filters</li> </ul></li> </ul> The idea that's used in the blog-post I linked to is to : <ul> <li>create a new PHP_Beautifier filter, that will detect the following tokens : <ul> <li><code>T_CLASS</code></li> <li><code>T_FUNCTION</code></li> <li><code>T_INTERFACE</code></li> </ul></li> <li>And add a "draft" doc-block just before them, if there is not already one</li> </ul> To run the tool on some <code>MyClass.php</code> file, I've had to first install <code>PHP_Beautifier</code> : <pre><code>pear install --alldeps Php_Beautifier-beta </code></pre> Then, download the filter to the directory I was working in (could have put it in the default directory, of course) : <pre><code>wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs cp phpDoc.filter.phpcs phpDoc.filter.php </code></pre> And, after that, I created a new <code>beautifier-1.php</code> script (Based on what's proposed in the blog-post I linked to, once again), which will : <ul> <li>Load the content of my <code>MyClass.php</code> file</li> <li>Instanciate <code>PHP_Beautifier</code></li> <li>Add some filters to beautify the code</li> <li>Add the <code>phpDoc</code> filter we just downloaded</li> <li>Beautify the source of our file, and echo it to the standard output.</li> </ul> The code of the <code>beautifier-1.php</code> script will like this : (Once again, the biggest part is a copy-paste from the blog-post ; I only translated the comments, and changed a couple of small things) <pre><code>require_once 'PHP/Beautifier.php'; // Load the content of my source-file, with missing docblocks $sourcecode = file_get_contents('MyClass.php'); $oToken = new PHP_Beautifier(); // The phpDoc.filter.php file is not in the default directory, // but in the "current" one => we need to add it to the list of // directories that PHP_Beautifier will search in for filters $oToken->addFilterDirectory(dirname(__FILE__)); // Adding some nice filters, to format the code $oToken->addFilter('ArrayNested'); $oToken->addFilter('Lowercase'); $oToken->addFilter('IndentStyles', array('style'=>'k&r')); // Adding the phpDoc filter, asking it to add a license // at the beginning of the file $oToken->addFilter('phpDoc', array('license'=>'php')); // The code is in $sourceCode // We could also have used the setInputFile method, // instead of having the code in a variable $oToken->setInputString($sourcecode); $oToken->process(); // And here we get the result, all clean ! echo $oToken->get(); </code></pre> Note that I also had to path two small things in <code>phpDoc.filter.php</code>, to avoid a warning and a notice... The corresponding patch can be downloaded there : <a href="http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch" rel="noreferrer">http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch</a> Now, if we run that <code>beautifier-1.php</code> script : <pre><code>$ php ./beautifier-1.php </code></pre> With a <code>MyClass.php</code> file that initialy contains this code : <pre><code>class MyClass { public function __construct($myString, $myInt) { // } /** * Method with some comment * @param array $params blah blah */ public function doSomething(array $params = array()) { // ... } protected $_myVar; } </code></pre> Here's the kind of result we get -- once our file is Beautified : <pre><code><?php /** * * PHP version 5 * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * @category PHP * @package * @subpackage Filter * @author FirstName LastName <mail> * @copyright 2009 FirstName LastName * @link * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version CVS: $Id:$ */ /** * @todo Description of class MyClass * @author * @version * @package * @subpackage * @category * @link */ class MyClass { /** * @todo Description of function __construct * @param $myString * @param $myInt * @return */ public function __construct($myString, $myInt) { // } /** * Method with some comment * @param array $params blah blah */ public function doSomething(array $params = array()) { // ... } protected $_myVar; } </code></pre> We can note : <ul> <li>The license block at the beginning of the file</li> <li>The docblock that's been added on the <code>MyClass</code> class</li> <li>The docblock that's been added on the <code>__construct</code> method</li> <li>The docblock on the <code>doSomething</code> was already present in our code : it's not been removed.</li> <li>There are some <code>@todo</code> tags ^^</li> </ul> Now, it's not perfect, of course : <ul> <li>It doesn't document all the stuff we could want it too <ul> <li>For instance, here, it didn't document the <code>protected $_myVar</code></li> </ul></li> <li>It doesn't enhance existing docblocks</li> <li>And it doesn't open the file in any graphical editor <ul> <li>But that would be much harder, I guess...</li> </ul></li> </ul> But I'm pretty sure that this idea could be used as a starting point to something a lot more interesting : <ul> <li>About the stuff that doesn't get documented : adding new tags that will be recognized should not be too hard <ul> <li>You just have to add them to a list at the beginning of the filter</li> </ul></li> <li>Enhancing existing docblocks might be harder, I have to admit</li> <li>A nice thing is this could be fully-automated</li> <li>Using Eclipse PDT, maybe this could be set as an External Tool, so we can at least launch it from our IDE ?</li> </ul>
Tags
Title
singulars
PostAcceptedAnswerId
1. This table or related slice is empty.
PostParentId
1. POA tool to add and complete PHP source code documentation
 singulars
 PostTypePostTypeId
 PTQuestion
PostTypePostTypeId
1. PTAnswer
UserLastEditorUserId
1. USkguest
UserOwnerUserId
1. USPascal MARTIN
plurals
PostLinksPostIdRelatedPostId
1. This table or related slice is empty.
PostLinksRelatedPostIdPostId
1. This table or related slice is empty.
PostsAcceptedAnswerId
1. POA tool to add and complete PHP source code documentation
 singulars
 PostTypePostTypeId
 PTQuestion
PostsParentIdCreationDate
1. This table or related slice is empty.
VotesPostIdCreationDate
1. VO
 singulars
 PostPostId
 PO
 UserUserId
 This table or related slice is empty.
 VoteTypeVoteTypeId
 VTUpMod
2. VO
 singulars
 PostPostId
 PO
 UserUserId
 This table or related slice is empty.
 VoteTypeVoteTypeId
 VTUpMod
3. VO
 singulars
 PostPostId
 PO
 UserUserId
 This table or related slice is empty.
 VoteTypeVoteTypeId
 VTUpMod
CommentsPostId

Querying!

Guidance

A row detail

Detail views are divided into sections. All the information in the data section comes from columns in the selected row. The other sections display data from other, related rows.

Related data can be related in a to-one or a to-many fashion. Captions of data related in a to-many fashion link to a list view showing a filtered view of the table.

Try moving around until you find a non-empty to-many entry and click on the label to get to one. You can move back to the root by clicking on the database name in the header.