Документирование кода PHP на основе DocBlock комментариев

Пример подсказок на основе DocBlock комментариев:

DocBlock – это многострочный комментарий переведенный к определенному виду (синтаксису). На основании этих комментариев можно автоматически генерировать документацию с помощью утилиты phpDocumentor. Пример генерируемой документации можно посмотреть на официальном сайте phpDocumentor.

И так разберем подробнее как использовать эти “чудо” комментарии.

• Пример использования DocBlock комментариев
• Описание тегов (дискрипторов) phpDoc

Пример использования DocBlock комментариев

Простой пример комментария:

1. <?php
2.  
3. /**
4. * Имя или краткое описание объекта
5. *
6. * Развернутое описание
7. *
8. * @имя_тега значение
9. * @return тип_данных
10. */
11.  

Комментарий должен находиться перед документируемым элементом (классом, функцией, переменной, константой).

Строка комментария должна начинаться с *. Блоки разделяются пустыми строками. Остальные комментарии не подходящий под данный синтаксис будут игнорироваться. Теги также могут находиться в описании объекта, такие теги заключаются в {} скобки и называются инлайн (inline) теги.

Пример с использованием инлайн тегов:

1. <?php
2.  
3. /**
4. * Имя или краткое описание объекта
5. *
6. * Развернутое описание
7. * Здесь мы будеи использовать инлайн {@inlinetag} тег
8. *
9. * @имя_тега значение
10. * @return тип_данных
11. */
12.  

Общий пример:

1. <?php
2.  
3. /**
4. * Краткое описание класса
5. *
6. * Подробное описание класса
7. * которое может растянуться на несколько строк с использованием HTML тегов.
8. * Теги можно использовать следующие:
9. * <b> — жирное начертание;
10. * <code> — код;
11. * <br> — разрыв строки;
12. * <i> — курсив;
13. * <kbd> — сочетание клавиш;
14. * <li> — элемент списка;
15. * <ol> — нумерованный список;
16. * <p> — абзац;
17. * <pre> — форматированный текст;
18. * <samp> — пример;
19. * <ul> — маркированный список;
20. * <var> — имя переменной.
21. * Инлайн тег. Использует данные с {@link http://кодер.укр/data.php}
22. * Далее будет список используемых тегов
23. *
24. * @author Coder UA <web@кодер.укр>
25. * @version 1.0
26. * @package MyPackageName
27. * @category MyCategoryNews
28. * @todo описание необходимых доработок
29. * @example http://кодер.укр/example.php
30. * @copyright Copyright (c) 2014, Coder UA
31. */
32. class ClassName {
33.  
34. /**
35. * Описание переменной, если необходимо
36. *
37. * @var array массив данных
38. */
39. public $var1 = array();
40.  
41. /**
42. * Описание переменной, если необходимо
43. *
44. * @var integer очень важные данные
45. */
46. private $var2;
47.  
48. /**
49. * Краткое описание функции
50. *
51. * Подробное описание функции, если необходимо
52. *
53. * @param string $param1 Первый параметр функции
54. * @param string $param2 Второй параметр
55. * @return string
56. */
57. function myFuncName ($param1, $param2 = ‘value’) {
59. //…
60. //код
61. //…
62.  
63. return $var;
64. }
65.  
66. //…
67.  
68. }

Еще пример:

1. <?php
2. /**
3. * Контроллер работы с новостями
4. *
5. * Выполняет обработку и вывод списка новостей и подробную информацию о новости
6. *
7. * @package Fronend
8. * @category News
9. * @author Coder UA <web@кодер.укр>
10. * @version 1.1
11. * @copyright Copyright (c) 2014, Coder UA
12. */
13. class NewsController extends Controller {
14.  
15. /**
16. * @var integer количество новостей на страницу в списке
17. */
18. public $limit = 10;
19.  
20. /**
21. * Вывод списка новостей
22. *
23. * @return array список новостей
24. */
25. public function actionIndex() {
27. //…
28. //код
29. //…
31. return $data;
32. }
33.  
34. /**
35. * Вывод подробной информации о новости
36. *
37. * @param integer $id – id текущей новости
38. * @return array данные о новости
39. */
40. public function actionDetail($id) {
42. //…
43. //код
44. //…
46. return $data;
47. }
48.  
49. //…
50.  
51. }

Описание основных тегов (дискрипторов) phpDoc

В конечном итоге при использовании docBlock комментариев Вы получите:

• Код с комментариями
• Подсказку IDE при использовании функций, методов и свойств, которые были прокомментированы с помощью docBlock
• Автоматически сгенерированную документацию с помощью phpDocumentor