Генератор документації

Генератор документації програма або пакет програм, що дозволяє отримувати документацію, призначену для програмістів (документація на API) та/або для кінцевих користувачів системи, з особливим чином коментованого початкового коду і, в деяких випадках, з виконуваних модулів (отриманими на виході компілятора).

Зазвичай генератор аналізує початковий код програми, виділяючи синтаксичні конструкції, що відповідають значущим об'єктам програми (типами, класам та їх членам/властивостями/методам, процедурам/функціям тощо). В ході аналізу також використовується мета-інформація про об'єкти програми, подана у вигляді документувальних коментарів. На основі всієї зібраної інформації формується готова документація, як правило, в одному із загальноприйнятих форматів HTML, HTMLHelp, PDF, RTF тощо.

Документувальні коментарі

Документувальний коментар — це особливим чином оформлений коментар до об'єкту програми, призначений для використання певним генератором документації. Від того, який генератор документації застосовується, залежить синтаксис конструкцій, що використовуються в документувальних коментарях.

У документувальних коментарях може міститися інформація про автора коду, описуватися призначення об'єкта програми, зміст вхідних і вихідних параметрів для функції/процедури, приклади використання, можливі виняткові ситуації, особливості реалізації.

Документувальні коментарі, як правило, оформляються як багаторядкові коментарі в стилі мови Сі. У кожному разі коментар розташовується перед документованим елементом. Першим символом у коментарі (та на початку рядків коментарю) має бути *. Блоки відокремлюються порожніми рядками.

Приклад документувального коментаря в мові PHP:

/**
* Назва або короткий опис об'єкта
* 
* Розгорнутий опис
* 
* @назва_дескриптора значення
* @return тип_даних
*/

Приклад документувального коментаря до функції в програмі на Java, призначеного для використання Javadoc:

 /**
 * Перевіряє, чи допустимий хід.
 * Наприклад, щоб задати хід e2-e4, напишіть isValidMove (5,2,5,4);
 * @author John Doe
 * @param theFromFile Вертикаль, на якій міститься фігура (1 = a, 8 = h)
 * @param theFromRank Горизонталь, на якій міститься фігура (1 ... 8)
 * @param theToFile Вертикаль клітинки, на яку виконується хід (1 = a, 8 = h)
 * @param theToRank Горизонталь клітинки, на яку виконується хід (1 ... 8)
 * @return true, якщо хід припустимий, і false, якщо неприпустимий
 */
 boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank)
 {
   . . .
 }

Популярні генератори документації

Приклади для різних мов і середовищ програмування:

Примітки

This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.