вторник, 19 апреля 2011 г.

Генерация документации для JavaScript


  • JsDoc toolkit
Плюсы: 
  1. ядро генератора написано на javascript, следовательно для генерации доков нужна только установленная java машина
  2. достаточно хорошее описание тэгов и есть примеры работы с ними. http://code.google.com/p/jsdoc-toolkit/w/list
  3. работает с русскими комментариями
Минусы:
  1. Возможно невозможно генерация доков для классов, находящихся в анонимной функции. Например:
include('class1.js', 'class2.js', function() {
       /**
       * Вот для этого класса не получится сгенерить доки
       * @class 
       * @constructor
       */
       var MyClass = function() {};
});

Генератор от Yahoo. Последняя версия вышла 12/05/2008 и до сих пор находится с пометкой beta.
Плюсы:
  1. Нет проблемы с классами внутри анонимных функций. см. выше
  2. Генерится красивый набор html-страниц. По оформления более удобный по сравнению с JsDoc
Минусы:
  1. Для запуска необходим python 2.* и дополнительные либы к нему.
    2. Не поддерживает комментарии на русском. Вылетает при выполнении при генерации исходников с подсветкой синтаксиса. Хотя есть решение. Я покапался в исходникам python. Все дело в том, что файлы читаются без учета кодировки.
    Чтобы скрипт хоть как-то отработал, нужно в файле yuidoc_highlight.py в строчке 57 написать так out.writelines(highlighted.encode("utf-8")), если конечно файл с js скриптом в utf-8 кодировке. Я не спец в python, так что возможно есть другой выход.

    + исправленная версия, с возможностью генерить доки с русскими комментариями
    http://narod.yandex.ru/disk/11862647001/yuidoc.rar