Документирование кода в phpDoc для Laravel 4

Question

Документирование кода в phpDoc для Laravel 4

Я хотел бы документировать только код, который я написал в phpDoc, я использую Laravel 4 как моя основа MVC фреймворк. Что было бы хорошим способом структурировать код так, чтобы я мог документировать свой код вместе со всеми вызывающими подпрограммами (например, routes.php) в документации. Как было бы очевидно, я не хочу документировать всю архитектуру MVC внутри Laravel.

Кроме того, возможно ли документировать вызовы функций в phpDoc?

0

documentation laravel-4 php phpdoc

Решение

Другие решения

Других решений пока нет …

Источник

Accepted Answer

phpDoc можно использовать в любое время и в любом месте, особенно для ООП.

Когда мы говорим об ООП, мы называем функцию как методы, однако в MVC мы обычно называем функции как действия. В любом случае вы можете следовать этой схеме:

<?php
/**
* @method int sum($a, $b)
* @license GPL
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @author Your Name <your@email.com>
*/
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

2