Генератор PhpDoc свойств(внутри все описано) 1.7

Выкладываем свои наработки
Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Генератор PhpDoc свойств(внутри все описано) 1.7

Сообщение nizsheanez »

Генератор DocBlock для Yii. Добавляет поддержку автодополнения для публичных геттеров, сеттеров, событий, скоупов, релейшенов, поведений, атрибутов моделей AR

Пример сгенерированных комментариев:

Код: Выделить всё

/** 
 * 
 * !Attributes - атрибуты БД
 * @property string           $language
 * @property string           $status
 * @property integer          $comments_denied
 * @property string           $id
 * @property string           $user_id
 * @property string           $title
 * @property string           $url
 * @property string           $text
 * @property string           $date_create
 * @property integer          $order
 * 
 * !Accessors - Геттеры и сеттеры класа и его поведений
 * @property                  $href
 * @property                  $content
 * @property                  $errorsFlatArray
 * @property                  $updateUrl
 * @property                  $createUrl
 * @property                  $deleteUrl
 * 
 * !Relations - связи
 * @property Language         $language_model
 * @property TagRel[]         $tags_rels
 * @property Tag[]            $tags
 * @property int|null         $comments_count
 * @property User             $user
 * @property PageSectionRel[] $sections_rels
 * @property PageSection[]    $sections
 * 
 * !Scopes - именованные группы условий, возвращают этот АР
 * @method   Page             published()
 * @method   Page             sitemap()
 * @method   Page             ordered()
 * @method   Page             last()
 * 
 */

 
Использование
1) Конфигурируется, как и любая консольная комманда Yii, однако сначала применяется базовая конфигурация: docBlock/configs/stdConfig.php, затем файл заданный через свойство $config из той же директори (для возможности задавать различные конфигурации из консоли), затем конфигурация из commandMap
2) Комманда работает с 2-мя итераторами: по файлам и по свойствам/методам класса - т.е. вы можете однозначно задать для каких файлов и каких свойств/методов генерировать dockBlock'и.
По умолчанию в качестве итератора по файлам используется ModelInModuleFilesIterator, он рекурсивно проходит по всем директориям вида /moduleId/models/*
А в качестве итератора по свойствам используется YiiComponentPropertyIterator - который обходит: attributes, events, accessors, relations, scopes

Список реализованных фич:
- Если геттер(сеттер) имеет больше нуля(одного) обязательных параметров, то он игнорируется.
- Если свойство уже описано в одном из родительских классов, то он игнорируется.
- Сгенерированные комментарии можно редактировать! т.е. если вы захотите добавить описание в блок комментариев(так называемые shortDescription и longDescription), то при перегенерации они будут сохранены(вы же старались!).
- Если для задания описания или типа свойства не хватило информации в текущих исходниках, то вы можете добавить их прямо в сгенерированный блок комментариев и они будут использоваться в дальнейшем и не потеряются при перегенерации. Конечно же, если информации в исходниках достаточно для генерации типа или комментария, то будет использована она, так что редактировать сгенерированные типы или комментарии бесполезно - нужно редактировать источник информации, например комментарии к геттеру.
- Аннотации author|api|category|deprecated|example|filesource|ignore|internal|license, link|package|see|since|subpackage|todo|version|uses|used-by будут сохранены(думаю этой простыни вам хватит)
- Преобразование стилей кодирования camelCaseToUnderscore (по умолчанию выключено, т.к. требует внешнего преобразователя)
- Ну и приятный бонус: вертикальное выравнивание (можно выключить)

Собственно ссылочка: https://github.com/nizsheanez/DocBlockGenerator
Последний раз редактировалось nizsheanez 2012.10.21, 17:05, всего редактировалось 7 раз.

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.1

Сообщение nizsheanez »

В версии 1.1 добавлено:

- Полная поддержка AR relations
- Добавлена возможность исключать группы свойств из результата, посредством DocBlockCommand::$propertyIteratorOptions - значения по умолчанию:

Код: Выделить всё

    'includeAttributes' => true,
    'includeEvents'     => false,
    'includeAccessors'  => true,
    'includeRelations'  => true

Аватара пользователя
slavcodev
Сообщения: 3134
Зарегистрирован: 2009.04.02, 21:42
Откуда: Valencia
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.1

Сообщение slavcodev »

раз пошла такая пьянка, вот мой phpDoc, может что-то понравится

Код: Выделить всё

/**
 * Attributes - атрибуты БД
 * @property ...
 *
 * Relations - связи
 * @property ...
 *
 * Behaviors - поведения и их атрибуты и методы, которые можно вызывать от имени АР
 * @property ...
 *
 * Scopes - именованные группы условий, возвращают этот АР
 * @method ...
 *
 * Getters and setters
 * @property ...
 */
Жду Yii 3!

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.1

Сообщение nizsheanez »

Да, пригодится, спасибо.
1) Надо добавить поддержку scopes.
2) Насчет комментов между блоками, тоже отличная идея, думаю я позаимствую. (хотя уже предвижу проблемы с парсингом описаний, challenge accepted)

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.2

Сообщение nizsheanez »

Версия 1.2
1) Добавлена поддержка scopes
2) Добавлена поддержка метода behaviors для любых компонентов, не обязательно ActiveRecord(нюанс - поведения должны аттачиться в конструкторе, иначе в лог высыпется ворнинг, который об этом попросит)
3) Пока принесена в жертву поддержка property-read/property-write - из-за сильного усложнения кода. Поддержка будет возвращена чуть позже.
4) Добавить дополнительные симпотные комментарии все еще планируется, но тоже чуть позже.

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.3

Сообщение nizsheanez »

Однако не тормозим - версия 1.3
1) Добавлены "mc-bear"-like комментарии.
2) В коробке есть файлы с переводами, в них можно задать свои комментарии(сейчас переводы жестко берутся из директории "core" в расширении, в следующей версии добавлю возможность конфигурирования, что бы можно было создать свою папочку переводов и без проблем обновляться)
3) Для перевода используется независимый от вашего приложения компонент перевода, поэтому если вы используете свой MessageSource, то вам нужно сделать... Ничего.
Последний раз редактировалось nizsheanez 2012.09.08, 00:19, всего редактировалось 3 раза.

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.3

Сообщение nizsheanez »

PS: Народ, я таки продолжаю собирать хотелки!

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение nizsheanez »

Прошедшие изменения:
1.4 - улучшенная конфигурируемость.
1.5 - общий рефакторинг - ничего интересного
1.6 - добавлено описание использования, теперь конфигурацией занимается CConfiguration, проверка классов на isInstantiable

Ekstazi
Сообщения: 1428
Зарегистрирован: 2009.08.20, 22:54
Откуда: Молдова, Бельцы
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение Ekstazi »

А можно ли сохранять старые @property, если они определены в поведении магически ?

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение nizsheanez »

т.е. задача считать PHPDoc с поведения, выковырять оттуда @property и добавить их в список @property родительского класса. Так?

Ekstazi
Сообщения: 1428
Зарегистрирован: 2009.08.20, 22:54
Откуда: Молдова, Бельцы
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение Ekstazi »

Нет. Не родительского класса. Сейчас они считаются частью родительского класса, а хотелось бы дочернего. К примеру, я создал поведение которое с попмощью __get и __set определяет нескеолько св-в и описал их в моделе, но, после обновления доков мои валидные @property теги исчезнут из доков.

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение nizsheanez »

Проблема тут в том, что бы определить является ли то что написано руками - реальным свойством, или мусором (раньше был геттер с таким именем, а теперь удалили, а @property для него пока осталось)
Самый тупой подход здесь - не удалять старые @property (можно сделать, как настраиваемый параметр) - конечно придется подчищать мусор руками.
А вот если делать по умному, то умного по этому поводу пока ничего в голову не приходит.

Собственно, как понять по имени @property и по коду класса, что __get реализует это @property?
(для CComponent все очевидно - пытается вызвать getPropertyName или onPropertyName, а вот если человек выходит за рамки этих соглашений, тогда что делать?)

Ekstazi
Сообщения: 1428
Зарегистрирован: 2009.08.20, 22:54
Откуда: Молдова, Бельцы
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение Ekstazi »

Элементарно:

Код: Выделить всё

try 
{
if($readable)
$t=$obj->$prop;
if($writable)
$obj->$prop=$t;
$hasProperty=true;
}catch(Exception $e)
{
$hasProperty=false;
} 

Ekstazi
Сообщения: 1428
Зарегистрирован: 2009.08.20, 22:54
Откуда: Молдова, Бельцы
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение Ekstazi »

CComponent выдает исключение при попытки доступа к неопределеному св-ву.

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение nizsheanez »

А! Ты прав. Можно же проверить в наглую! Попытаться прочитать или записать. И такую же штуку надо для @method сделать.
Постараюсь сегодня до вечера реализовать.

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.6

Сообщение nizsheanez »

А вот и обещанное:
1.7
- сохранение пользовательских @property и @method
- файлы не редактируются, если изменять в них нечего.

Аватара пользователя
yiijeka
Сообщения: 3091
Зарегистрирован: 2012.01.28, 09:14
Откуда: Беларусь
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.7

Сообщение yiijeka »

У меня ошибка:

PHP Error[2]: include(ConfigForm.php): failed to open stream: No such file or director
in file E:\server\domains\test\protected\common\lib\Yii\YiiBase.php at line 421
#0 E:\server\domains\test\protected\common\lib\Yii\YiiBase.php(421): autoload()
#1 unknown(0): autoload()
#2 unknown(0): spl_autoload_call()
#3 E:\server\domains\test\protected\console\commands\DocBlockCommand.php(110): ReflectionClass->__construct()
#4 E:\server\domains\test\protected\console\commands\DocBlockCommand.php(77): DocBlockCommand->getClassInstance()
#5 unknown(0): DocBlockCommand->actionIndex()
#6 E:\server\domains\test\protected\common\lib\Yii\console\CConsoleCommand.php(172): ReflectionMethod->invokeArgs()
#7 E:\server\domains\test\protected\common\lib\Yii\console\CConsoleCommandRunner.php(67): DocBlockCommand->run()
#8 E:\server\domains\test\protected\common\lib\Yii\console\CConsoleApplication.php(91): CConsoleCommandRunner->run()
#9 E:\server\domains\test\protected\common\lib\Yii\base\CApplication.php(169): CConsoleApplication->processRequest()
#10 E:\server\domains\test\protected\common\lib\Yii\yiic.php(33): CConsoleApplication->run()
#11 E:\server\domains\test\protected\console\yiic.php(14): require_once()

Может из за того, что использованы namespace ? Хотя убрал из этого файла namespace, все равно ругается также.

Аватара пользователя
nizsheanez
Сообщения: 814
Зарегистрирован: 2011.04.29, 13:09
Откуда: Москва

Re: Генератор PhpDoc свойств(внутри все описано) 1.7

Сообщение nizsheanez »

ConfigForm.php - видимо я где-то его использовал... странно...

Аватара пользователя
XAKEPEHOK
Сообщения: 38
Зарегистрирован: 2012.08.16, 13:11
Откуда: КМВ
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.7

Сообщение XAKEPEHOK »

Та же ошибка
include(LoginForm.php) [function.include]: failed to open stream: No such file or directory (C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\YiiBase.php:421)


#0 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\YiiBase.php(421): CWebApplication->handleError()
#1 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\YiiBase.php(421): autoload()
#2 unknown(0): autoload()
#3 unknown(0): spl_autoload_call()
#4 C:\WebServer\domains\homyak\protected\commands\docBlock\DocBlockCommand.php(110): ReflectionClass->__construct()
#5 C:\WebServer\domains\homyak\protected\commands\docBlock\DocBlockCommand.php(77): DocBlockCommand->getClassInstance()
#6 unknown(0): DocBlockCommand->actionIndex()
#7 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\console\CConsoleCommand.php(172): ReflectionMethod->invokeArgs()
#8 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\console\CConsoleCommandRunner.php(71): DocBlockCommand->run()
#9 C:\WebServer\domains\homyak\protected\extensions\yiiext\modules\webshell\controllers\DefaultController.php(72): CConsoleCommandRunner->run()
#10 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\web\actions\CInlineAction.php(49): DefaultController->actionYiic()
#11 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\web\CController.php(308): CInlineAction->runWithParams()
#12 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\web\CController.php(286): DefaultController->runAction()
#13 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\web\CController.php(265): DefaultController->runActionWithFilters()
#14 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\web\CWebApplication.php(282): DefaultController->run()
#15 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\web\CWebApplication.php(141): CWebApplication->runController()
#16 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\base\CApplication.php(169): CWebApplication->processRequest()
#17 C:\WebServer\domains\homyak\protected\components\WebApplicationEndBehavior.php(25): CWebApplication->run()
#18 unknown(0): WebApplicationEndBehavior->runEnd()
#19 C:\WebServer\domains\yiiframework\yii-1.1.13.e9e4a0\framework\base\CComponent.php(261): call_user_func_array()
#20 C:\WebServer\domains\homyak\index.php(27): CWebApplication->__call()
#21 C:\WebServer\domains\homyak\index.php(27): CWebApplication->runEnd()
Большинство неправильных шагов совершаются стоя на месте

Аватара пользователя
XAKEPEHOK
Сообщения: 38
Зарегистрирован: 2012.08.16, 13:11
Откуда: КМВ
Контактная информация:

Re: Генератор PhpDoc свойств(внутри все описано) 1.7

Сообщение XAKEPEHOK »

Фишка в том, что файла LoginForm.php у меня нет, и выдралось оно похоже из phpdoc, т.к. раньше класс назывался LoginForm, а теперь FormLogin (и файл соответственно). Phpdoc убрал, но ошибка все равно есть
Большинство неправильных шагов совершаются стоя на месте

Ответить