Bence PHP_Codesniffer can indicate when there is no docblock -- see the examples of reports on this page (quoting one of those):
--------------------------------------------------------------------------------
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
--------------------------------------------------------------------------------
Ben en azından bir belge yok tüm dosyaları / sınıfları / yöntemlerinin bir listesini almak için PHP_Codesniffer kullanabilirsiniz varsayalım; Hatırladığım kadarıyla, bazı otomatik aracını kullanarak ayrıştırmak için daha kolay olurdu çıkış olarak XML üretebilir - bazı bilgilendirme kısmı-jeneratör ilk adım olabilir ;-)
Also, if you are using phpDocumentor to generate the documentation, can this one not report errors for missing blocks ?
Testlerin bir çift sonra, bu olabilir - örneğin, bu gibi --undocumentedelements seçeneği ile, çok değil belgelerle birlikte bir sınıf dosya üzerinde çalışan:
phpdoc --filename MyClass.php --target doc --undocumentedelements
Çıktının ortasında bu verir:
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
Bu eksik bilgilendirme kısmı oluştururken gelince, burada da, bir raporlama aracı olarak yararlı olsa bile, bu yararlı değil ...
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...
... Hangi güzel çalışıyor: Eksik bilgilendirme kısmı bir çift daha genel olarak her gün değil, bu nedenle görev (and Eclipse PDT provides a feature to pre-generate the docblock for a method, when you are editing a specific file/method) elle yapılabilir.
Appart bu, ben gerçekten bilgilendirme kısmı oluşturmak için herhangi bir tam otomatik bir araç bilmiyorum ... Ama ben de kullanarak, biz ilginç bir araç yaratmak için yönetmek olabilir eminim:
After a bit more searching, though, I found this blog-post (it's in french -- maybe some people here will be able to understand) : Ajout automatique de Tags phpDoc à l'aide de PHP_Beautifier.
*Possible translation of the title : "Automatically adding phpDoc tags, using PHP_Beautifier"*
Fikir aslında kötü değil:
- The
PHP_Beautifier tool is pretty nice and powerful, when it comes to formating some PHP code that's not well formated
- Bunu ben bile okuyamadım kodu için birçok kez ^ ^ kullandım
- And it can be extended, using what it calls "filters".
: Ben bağlantılı blog-sonrası kullanılan fikir olduğunu
- create a new PHP_Beautifier filter, that will detect the following tokens :
T_CLASST_FUNCTIONT_INTERFACE
- Zaten bir yoksa ve sadece onlardan önce bir "taslak" doc-blok eklemek
To run the tool on some MyClass.php file, I've had to first install PHP_Beautifier :
pear install --alldeps Php_Beautifier-beta
Sonra, ben çalışıyordu dizine filtreyi indirebilirsiniz (could have put it in the default directory, of course):
wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs
cp phpDoc.filter.phpcs phpDoc.filter.php
Ve bundan sonra, ben yeni bir beautifier-1.php komut (Based on what's proposed in the blog-post I linked to, once again), oluşturduğunuz olacak:
- Benim
MyClass.php dosyasının içeriğini yükleyin
- Instanciate
PHP_Beautifier
- Kodunu güzelleştirmek için bazı filtreler ekle
- Biz sadece indirilen
phpDoc filtre ekle
- Bizim dosyanın kaynağını güzelleştirmek ve standart çıktıya echo.
The code of the beautifier-1.php 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)
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();
Note that I also had to path two small things in phpDoc.filter.php, to avoid a warning and a notice...
The corresponding patch can be downloaded there : http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch
Now, if we run that beautifier-1.php script :
$ php ./beautifier-1.php
Initialy bu kodu içeren bir MyClass.php dosyası:
class MyClass {
public function __construct($myString, $myInt) {
//
}
/**
* Method with some comment
* @param array $params blah blah
*/
public function doSomething(array $params = array()) {
// ...
}
protected $_myVar;
}
Burada olsun sonuç tür - bizim dosya güzelleştiren bir kez:
<?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;
}
Biz dikkat edebilirsiniz:
- Dosyanın başında lisans blok
MyClass sınıfına eklendi oldu bilgilendirme kısmı__construct yöntemi eklendiğini bilgilendirme kısmı- Üzerine bilgilendirme kısmı
doSomething zaten bizim kodunda mevcut oldu: kaldırıldı değil.
- Bazı
@todo etiketler ^ ^ vardır
Now, it's not perfect, of course :
- It doesn't document all the stuff we could want it too
- Örneğin, burada, bu belge vermedi
protected $_myVar
- Bu, mevcut bilgilendirme kısmı geliştirmek değil
- And it doesn't open the file in any graphical editor
- Ama bu çok daha zor olurdu sanırım ...
But I'm pretty sure that this idea could be used as a starting point to something a lot more interesting :
- About the stuff that doesn't get documented : adding new tags that will be recognized should not be too hard
- Sadece filtrenin başında bunları bir listeye eklemek zorunda
- Varolan bilgilendirme kısmı Geliştirilmesi zor olabilir, itiraf etmeliyim
- Güzel bir şey bu tamamen otomatik olabilir olduğu
- Eclipse PDT kullanarak, belki de bu bir External Tool olarak ayarlanmış olabilir, bu yüzden en azından bizim IDE başlatabilirsiniz?
