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

Генератор документації — програма або пакет програм, що дозволяє отримувати документацію, призначену для програмістів (документація на 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)  {  . . .  } 

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

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

• Doc-O-Matic;
• ^[en] призначений для програм мовами VB6, VB.NET/C#/Visual C++ .NET (.NET Framework 1.0, 1.1 і 2.0), COM-компонентів, баз даних Access, Microsoft SQL Server і Oracle, XML Schema та іншими мовами опису XML;
• Doxygen — мовами , Сі, Objective-C, Java, IDL, PHP, C#, Фортран, VHDL, Python і, частково, D;
• ^[ru] — мовою Python;
• Javadoc — мовою Java;
• JSDoc — мовою JavaScript;
• ;
•  — мовою Delphi/Pascal;
• ^[en] — мовою Perl (включений в стандартний дистрибутив);
• ^[ru] і PHPDoc (адаптація Javadoc для використання з PHP) — мовою PHP;
• POD — мовою Perl;
• ^[en] — мовою Ruby;
• ^[en];
• ;
• ^[en] — мовами C#, VB.NET та іншими мовами платформи .NET;
• ^[en] — для C#, VB.NET та іншими мовами платформи .NET;
• Sphinx — мовою Python;
• ^[en] — мовою VB6;
• ^[en] (раніше VBdocman .NET) — мовами VB.NET і C#;
• WEB / CWEB;
• ^[ru] — мовою Delphi (входить до складу бібліотеки KOL/MCK).
• PHPDox [ 30 липня 2020 у Wayback Machine.] — проекти PHP.

Примітки

1. . Архів оригіналу за 27 листопада 2020. Процитовано 9 серпня 2020.
2. . Архів оригіналу за 20 грудня 2016. Процитовано 9 серпня 2020.
3. . Архів оригіналу за 30 січня 2009. Процитовано 9 серпня 2020.
4. . Архів оригіналу за 6 червня 2022. Процитовано 10 червня 2022.
5. . Архів оригіналу за 13 травня 2011. Процитовано 9 серпня 2020.
6. . Архів оригіналу за 3 липня 2006. Процитовано 9 серпня 2020.
7. http://www.helixoft.com/vbdocman/^{[недоступне посилання]}