Порівняльний аналіз генераторів документації

Размещено на http://www.allbest.ru/

Размещено на http://www.allbest.ru/

Національний технічний університет України “КПІ ім. І. Сікорського”

Порівняльний аналіз генераторів документації

Касянчук Дмитро Павлович, студент

Касянчук Д.П. Порівняльний аналіз генераторів документації

У статті описані переваги та недоліки різних генераторів. Проведено порівняльний аналіз заявлених генераторів для виявлення найбільш якісних та детальних серед них. Приведені ілюстрації їхнього синтаксису та результатів роботи.

Ключові слова: генератор документації, комерційна розробка, програміст, мови програмування, синтаксис, коментар.

Касянчук Д.П. Сравнительный анализ генераторов документации

В статье описаны преимущества и недостатки различных генераторов. Проведен сравнительный анализ заявленных генераторов для выявления наиболее качественных и детальных среди них. Приведены иллюстрации их синтаксиса и результаты работы.

Ключевые слова: генератор документации, коммерческая разработка, программист, языки программирования, синтаксис, комментарий.

Kasianchuk Dmytro. Comparative analysis of documentation generators

The article describes the advantages and disadvantages of various generators. A comparative analysis of the declared generators was carried out to identify the most high- quality and detailed ones among them. Translated illustrations of their syntax and results.

Keywords: documentation generator, commercial development, programmer, programming languages, syntax, commentary.

Постановка проблеми

Генератор документації -- це програма, результатом виконання якої є отримання документації призначеної для програмістів або користувачів системи. Принцип роботи таких програм полягає в аналізі вихідного коду для знаходження синтаксичних конструкцій, які відповідають головним об'єктам програми (тип, метод, функція, процедура і т.д.). Спираючись на всю зібрану інформацію формується документація в одному з форматів -- HTML, HTMLHelp, PDF, RTF та інших [3]. Залежно від того, який генератор використовується, є відмінності і в синтаксисі конструкцій, які наявні в документованих коментарях.

Документований коментар -- спеціальним чином оформлений коментар, що відповідає певному об`єкту програми [3]. Як правило, вони можуть містити інформацію про автора коду, зміст вхідних і вихідних параметрів для функції і тому подібне. Загалом документація необхідна і дуже важлива для комерційної розробки, адже вона допомагає розібратися з тим, як працює система за менший період часу, а генератори, в свою чергу, значно зменшують кількість часу для створення документації.

Формування мети дослідження

Метою роботи є аналіз певних генераторів документації для порівняння, що дає змогу виявити переваги і недоліки кожного з них. Порівнюватися будуть наступні генератори: D oxygen, JSDoc, Sphinx, JSDuck, Slate.

генератор документація

Порівняльний аналіз генераторів документації

Doxygen (рис. 1) -- використовується з такими мовами як С++, С, С#, Fortran, PHP, IDL, Java, VHDL, Objective-C, Python[4]. Даний генератор може сформувати документацію, яка буде містити в собі посилання, діаграми класів, викликів і т.п. в різних форматах: HTML, LaTeX, CHM, RTF, PostScript, PDF, man-сторінки. Doxygen дуже простий і зрозумілий в налаштуванні та установці. Його особливістю є можливість генерації документації не тільки на основі вихідного коду, а й на недокументованому вихідному коді. Також слід зазначити, що в документації, представленій в HTML форматі, реалізована можливість зручного пошуку, а також є посилання на зовнішню документацію. Якщо при роботі з Doxygen користувачу знадобилося задати додаткові параметри для майбутньої документації, то це можна зробити використовуючи конфігураційний файл, який являє собою звичайний текстовий формат. Проте слід зазначити і те, що для роботи з цим файлом існує декілька програм з графічним інтерфейсом, і це суттєво полегшує налаштування конфігураційного файлу. До мінусів можна віднести те, що цей генератор не має справжнього модульного налаштування.

Рис. 1. Результат роботи генератора Doxygen

Рис. 2. Приклад синтаксису для JSDoc

JSDoc (рис.2) -- це генератор документації в HTML форматі з вихідного коду на мові JavaScript. До переваг даного компілятора слід віднести те, що ядро генератора написане на мові JavaScript, а тому для генерації документації треба лише встановлена java-машина і більше ніяких додаткових файлів. Також плюсом є наявність великої кількості прикладів використання JSDoc, що значно полегшує його освоєння. Також реалізована можливість роботи з коментарями російською мовою. Але існує і певний недолік, а саме, неможливість генерації документації для класів, які знаходяться в анонімній функції. Приклад такого класу:

mdude('dassLjs', 'dass2.js', Шп^юпО {

/**

* Для цього класу генерація неможлива

* @dass

* @constructor

*/

var MyClass = ШпоіюпО {};

});

Рис. 3. Результат роботи генератора Sphinx

Sphinx (рис.3) -- генератор, який спочатку створювався лише для мови Python, але потім розробники додали підтримку С та С++ і планується додати підтримку ще більшої кількості популярних мов програмування. Принцип роботи генератора Sphinx в тому, що він перетворює файл в форматі reStructuredText в HTML, PDF, man та інші[5]. reStructuredText -- це полегшена мова розмітки. Даний генератор легко встановити і він доступний для всіх операційних систем, які підтримують мову Python. До недоліків можна віднести те, що для використання Sphinx потрібно додатково розібратися з reStructuredText.

Рис. 4. Приклад синтаксису JSDuck

JSDuck (рис.4) - генератор документації, цікавою особливістю якого є можливість використовувати його для будь-якого коду за умови, що цей код задокументовано відповідно до стандартів [2]. Також JSDuck відзначається легкістю в установці та використанні. Ще однією особливістю можна назвати те, що цей генератор може аналізувати код і генерувати документацію навіть без стандартних блоків. Реалізована можливість додавання спеціальних сторінок, а саме: сторінка привітання, сторінка з категоріями, сторінка з інструкціями, сторінка з прикладами. По підсумкам опитування, яке проводилося серед користувачів JSDuck, було зроблено висновок, що це дуже простий в розумінні і використанні генератор документації, недоліків якого не виявлено.

Рис. 5. Інтерфейс генератора документації Slate

Slate (рис.5) -- це генератор, який має інтуїтивно зрозумілий дизайн, він адаптивний і тому з ним можна працювати як на комп'ютерах так і на планшетах, ноутбуках, телефонах [1]. Slate має посилання на різні пункти документації, що допомагає користувачу швидко знайти потрібний розділ. Також цей генератор використовує Markdown і це спрощує розуміння та редагування. Ще одним плюсом для даного генератора є реалізована можливість підсвічування для 60-ти різних мов програмування і це додає комфорту до роботи з ним.

В таблиці 1 зображена оцінка за 5-ти бальною шкалою всіх засобів за трьома критеріями, які є важливими для генератора документації, а саме: кількість підтримуваних мов, кількість вихідних форматів та інтерфейс користувача. Інтерфейс користувача оцінювався за такими параметрами, як: зручність, відповідність сучасним тенденціям, а також нативність. Варто зазначити, що оцінка інтерфейсу - це суб'єктивна оцінка автора, а кількість підтримуваних мов і вихідних форматів - це значення, яке пропорційне статистичним даним взятим з різних джерел інформації. Сумарна оцінка вираховувалася, як середнє арифметичне цих оцінок.

Таблиця 1. Порівняння генераторів документації за різними критеріями

Висновок

Генератор документації -- це дуже корисний і важливий інструмент в арсеналі програміста, тому він повинен бути зручним, зрозумілим, простим і детальним. З огляду на все вищесказане, можна назвати JSDuck беззаперечним лідером серед представлених генераторів документації. Цей генератор має всі якості, якими повинен бути наділений потужний інструмент для генерації документації. Реалізована підтримка для всіх мов програмування, що робить його універсальним генератором, який підійде для розробника на будь-якій мові програмування. Не поступається JSDuck і генератор Slate, він підтримує 60 мов програмування, а також з ним можна працювати знаходячись будь-де, адже він має адаптивний дизайн і чудово виглядає як на екрані комп'ютера, так і на телефоні. Проте, якщо Ви розробник на мові С, C++, Python, то для Вас будуть цікаві і такі генератори, як Sphinx та Doxygen. Вони зрозумілі, зручні та детальні. Хоча слід пам'ятати і те, що для використання Sphinx буде потрібно розібратися з reStmcturedText. Якщо Вам цікаві генератори документації для мови JavaScript, то слід звернути увагу на JSDoc. З використанням цього генератору легко розібратися, адже існує велика кількість прикладів, а також він не потребує додаткових файлів для установки. Проте проблема генератору в тому, що він не генерує документацію для класів, які знаходяться в анонімній функції.

Список бібліографічного опису

1. Slate API Docs Generator, https://ruprogi.ru/software/slate-api-docs-generator

2. JSDuck -- генератор документации, https://habr.com/ru/post/214591/

3. Генератор документации, https://ru.wtkipedia.org/wiki/Генератор_документации

4. Doxygen, http://www.doxygen.nl

5. Sphinx, https://www.sphinx-doc.org

References

1. Slate API Docs Generator, https://ruprogi.ru/software/slate-api-docs-generator

2. JSDuck -- generator documentacii, https://habr.com/ru/post/214591/

3. Generator documentacii, https://ru.wikipedia.org/wiki/TeHepaTOp_goKyMeHrapHH

4. Doxygen, http://www.doxygen.nl

5. Sphinx, https://www.sphinx-doc.org

Размещено на Allbest.ru