0
Twin//Slash © 2010 <ul>Использование комментариев phpDocumentor </ul>
Важность документации <ul>” Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is b...
phpDocumentor <ul>Комментарии – важная часть кода Комментарии должны быть: <li>полными
точными
своевременными </li></ul>
phpDocumentor <ul><li>Он же  PHPDoc
http://www.phpdoc.org/ </li></ul>
Комментарии <ul><li>Комментарии  PHPDoc  пишутся в специально отведенных для них местах с помощью специальной разметки.
Могут быть сконвертированы в HTML, PDF или CHM файлы
$ phpdoc -h </li></ul>
Комментарии <ul>Комментарии PHPDoc всегда многострочные и выглядят следующим образом /** * Комментарий */ Как правило, все...
Комментарии <ul><li>HTML или wiki разметка внутри текста комментариев </li></ul><ul>/** * Внутри функции * * создаем перем...
<ul>Комметария </ul><ul>Комментариями PHPDoc сопровождается <li>каждый файл
каждый класс
каждое свойство или константа класса
каждый метод класса
каждая функция </li></ul>
Теги <ul><li>@<тег> <информация тега если есть>
/**
* @param string $name Имя пользователя
*/ </li></ul>
Основные теги <ul><li>@author Автор с указанием e-mail
/**
Upcoming SlideShare
Loading in...5
×

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

6,802

Published on

Published in: Technology
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
6,802
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
32
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

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

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

    Clipping is a handy way to collect important slides you want to go back to later.

×