Документирование кода в phpDoc для Laravel 4
Я хотел бы документировать только код, который я написал в phpDoc, я использую Laravel 4 как моя основа MVC фреймворк. Что было бы хорошим способом структурировать код так, чтобы я мог документировать свой код вместе со всеми вызывающими подпрограммами (например, routes.php) в документации. Как было бы очевидно, я не хочу документировать всю архитектуру MVC внутри Laravel.
Кроме того, возможно ли документировать вызовы функций в phpDoc?
Решение
phpDoc можно использовать в любое время и в любом месте, особенно для ООП.
Когда мы говорим об ООП, мы называем функцию как методы, однако в MVC мы обычно называем функции как действия. В любом случае вы можете следовать этой схеме:
<?php
/**
* @method int sum($a, $b)
* @license GPL
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @author Your Name <[email protected]>
*/
class Calc
{
/**
* Sums the first value with the second value
*
* @param int|float $a //First Param
* @param int|float $b //Second Param
* @example echo sum(2, 3); //returns 5
* @since 1.1 //Version
* @return int|float $result //Value Returned (use void if doesn't return)
*/
public function sum($a, $b)
{
/**
* @todo Needs implement validation
*/
return $result = $a + $b;
}
}
Если вы хотите использовать функции, следуйте тому же шаблону:
/**
* Returns Hello, $name
*
* @param string $name
*/
function hello($name) {
{
printf('Hello, %s', $name);
}
The Routes of Laravel использует анонимные функции, аналогичные jQuery, однако вы также можете использовать PhpDoc:
/**
* Route for user
*
* @uses Route::get()
* @example http://url.com/user/john
* @param string $name
*/
Route::get('user/{name?}', function($name = 'John')
{
return $name;
});
Более задокументированным способом может быть присвоение имени вашей функции и последующий вызов:
/**
* Route for user
*
* @uses Route::get()
* @example http://url.com/user/john
* @param string $name
*/
function route_user_name($name = 'John')
{
return $name;
});
Route::get('user/{name?}', route_user_name($name));
Проверьте больше на официальном сайте: http://www.phpdoc.org/
PS: большинство IDE или текстовых редакторов имеют плагин (расширение), чтобы сделать его проще, чем для Sublime Text: https://github.com/SublimeText/PhpDoc
Другие решения
Других решений пока нет …