• Like
Система документации phpDocumentor
Upcoming SlideShare
Loading in...5
×

Система документации phpDocumentor

  • 6,187 views
Uploaded on

 

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
6,187
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
30
Comments
0
Likes
3

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. Twin//Slash © 2010
      Использование комментариев phpDocumentor
  • 2. Важность документации
      ” Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.” Dick Brandon
  • 3. phpDocumentor
      Комментарии – важная часть кода Комментарии должны быть:
    • полными
    • 4. точными
    • 5. своевременными
  • 6. phpDocumentor
    • Он же PHPDoc
    • 7. http://www.phpdoc.org/
  • 8. Комментарии
    • Комментарии PHPDoc пишутся в специально отведенных для них местах с помощью специальной разметки.
    • 9. Могут быть сконвертированы в HTML, PDF или CHM файлы
    • 10. $ phpdoc -h
  • 11. Комментарии
      Комментарии PHPDoc всегда многострочные и выглядят следующим образом /** * Комментарий */ Как правило, все современные IDE автоматически поддерживают и дополняют такой блок комментариев.
  • 12. Комментарии
    • HTML или wiki разметка внутри текста комментариев
      /** * Внутри функции * * создаем переменную * * уничтожаем переменную */
  • 13.
      Комметария
      Комментариями PHPDoc сопровождается
    • каждый файл
    • 14. каждый класс
    • 15. каждое свойство или константа класса
    • 16. каждый метод класса
    • 17. каждая функция
  • 18. Теги
    • @<тег> <информация тега если есть>
    • 19. /**
    • 20. * @param string $name Имя пользователя
    • 21. */
  • 22. Основные теги
    • @author Автор с указанием e-mail
    • 23. /**
    • 24. * @author Aliaksei Shytkin < [email_address] >
    • 25. * @author Mahatma Harash <krishna@gmail.ind>
    • 26. */
  • 27. Основные теги
    • @version $Id$
    • 28. Версия с автоматическим подставлением информации о последней ревизии файла
  • 29. Основные теги
    • @package <имя пакета>
    • 30. @subpackage <имя подпакета>
    • 31. Для указания структуры проекта
    • 32. /**
    • 33. * @package Form
    • 34. */
  • 35. Основные теги
    • @var <тип переменной> <описание>
    • 36. Для свойств классов
    • 37. Тип переменной используется IDE для автокомплита
    • 38. /**
    • 39. * @var sfGuardUser Владелец экземпляра класса
    • 40. */
    • 41. $owner = null;
  • 42. Основные теги
    • @param <тип переменной> имя <описание>
    • 43. Для функций и методов
    • 44. Тип переменной используется IDE для автокомплита
    • 45. /**
    • 46. * @param sfGuardUser $user Пользователь оплачивающий ордер
    • 47. * @param mixed $order Данные ордера
    • 48. */
    • 49. public function process($user, $order){}
  • 50. Основные теги
  • 59. Основные теги
    • @todo <указание как в будущем изменить код>
    • 60. /**
    • 61. * @todo Перенести в шаблоны
    • 62. */
    • 63. public function translateTitle()
    • 64. {
    • 65. return __($this->title);
    • 66. }
  • 67. Пример
      Живой пример написания кода с комментариями
  • 68. Другие комментарии
      Имеет смысл оставлять важные комментарии внутри блоков кода, если они необходимы. Комментарии ставятся на строке перед комментируемым блоком кода. В данном случае все комментарии однострочные с пробелом после знака комментария
  • 69. Другие комментарии
      // проверка на действительность // пользователя if ($user->is_active && $user->registered_at == '01-01-2001') { }
  • 70. Комментарии symfony
      В фреймворке symfony комментарии необходимы
    • для каждого из подключаемого плагина в файле ProjectConfiguration.class.php
    • 71. для каждой инструкции внутри файла ProjectConfiguration.class.php
    • 72. для каждой связи события $this->dispatcher->connect в файле конфигурации приложения
  • 73. Комментарии YAML
      Опыт показывает необходимость комментирования YAML-файлов
    • к каждой важной инструкции в конфигурационных файлах проекта и приложения, к каждому из подключаемых хелперов и модулей , к каждому роутингу
    • 74. к каждому полю модели в yaml файле модели и другим инструкциям внутри файла модели
  • 75. Комментирование YAML
      # таблица для хранения заявок Tender: columns: # имя name: type: string(255) # описание description: type: clob
  • 76. Спасибо за внимание
      Вопросы?