Xpoint
   [напомнить пароль]

Документирование javascript

Метки: [без меток]
2009-02-21 23:56:43 [обр] Александр Петров(0/4)[досье]

Пришел к выводу что нужна документация к моим библиотекам на javascript. Самой популярной и пожалуй единственной является JSDoc. Но у нее недостаток. Я использую в большинстве случаев описание типа

var Ajax = {...}
var ChangeOpacity = {...}

Почему-то нравиться так писать.
Так вот этот документатор при парсинге ищет определение function, а если не встречает (как в моем случае) то считает что в скрипте определены одни переменные и ни чего не документирует.

Может кто подскажет, или другой документатор, или какое исправление к этому?

спустя 1 день 11 часов [обр] Александр Петров(0/4)[досье]
Вот делема или переписать по общепризнанным стандартам, что трудновато много кода, либо пытаться исправить документатор. Просто действительно так писать лично для меня в javascript удобнее, код читабельнее.
спустя 32 минуты [обр] Александр Петров(0/4)[досье]
var x = function (){}
он тоже не понимает, какой это тогда к черту JavaScript документатор. Написали бы C подобный как все остальные
спустя 6 минут [обр] Александр Петров(0/4)[досье]
Наверное надо свой документатор писать учитывая особенности синтаксиса JavaScipt.
спустя 8 часов [обр] Александр Петров(0/4)[досье]

Смотрите, что я придумал, а если комментарии оформлять в виде XML, к стате позже покапавшись я узнал что это практикуется в .Net и С#. т.е. примерно так

/// <autor>Петров petav@inbox.ru</autor> 
/// <version>1.0</version>
/// <class name="Ajax">
/// <summary>Набор инструментов для работы с Ajax</summary>
/// <param name='location' type='string'>Вызываемый адресс</param>
/// <param name='option' type='object'>Объект с обработчиками событий и опциями вызова</param>
/// <return type='object'><return/>
var Ajax = {
   //Здесь можно придумать теги описывающие методы, свойства. (К сожалению стандарта описывающего XML по моему нету)
}
/// </class>

Затем легко пропарсить и изъять чистый XML наложить на XSLT-шаблон и сделать что угодно хоть для каких систем, хочешь CHM, HTML, другой XML, PDF.
Прокомментируйте пожалуйста!!!!

спустя 3 минуты [обр] Александр Петров(0/4)[досье]

можно конечно использовать

/**
 * This is an unattached (static) function that adds two integers together.
 * @param {int} One The first number to add 
 * @param {int http://jsdoc.sourceforge.net/} Two The second number to add 
 * @author Gabriel Reid
 * @deprecated So you shouldn't use it anymore!
 */

как в JsDoc. Потом в XML и оттуда куда угодно.
Можно даже сервис создать. Заходишь на сайт даешь ему JS файл, а он тебе в ответ сгенерирует файл документации вы его сохранили и все...

спустя 2 дня 2 часа [обр] Александр Петров(0/4)[досье]
Вообщем много времени у меня заняло исследование этого вопроса. Искал основываясь на том что эти проблемы должны быть уже решены. JavaScript и его анонимному описанию много лет. Есть два продукта, один вышесказанный для perl и аналог только написанный на java http://code.google.com/p/jsdoc-toolkit/wiki/CookBook. Документация вполне исчерпывающая, все теги описаны. А главное обещано что с анонимными объектами работать будет. К стате входит в aptana sdutio (моё открытие) профессиональный редактор javaScript. Ни то не другое пока не пробывал. Завтра будут испытания и подробности с полигона.
спустя 14 минут [обр] Александр Петров(0/4)[досье]
Это вселяет надежды:
// Here's how to define a mixin API
/**
 * Document Observable class here
 * @class
 */
var Observable =
 /**
  * This is an API that can be mixed into other objects
  * @lends Observable#
  */
 {
  observe: function(callback) {
    //...
  },
  notify: function(event) {
    //...
  }
 };
спустя 17 часов [обр] Александр Петров(0/4)[досье]
jsdoc-toolkit + Aptana studio = то что нужно
спустя 8 минут [обр] Александр Петров(0/4)[досье]
jsdoc-toolkit составляет мнение о документе по коду если не может по коду то по тегам @class, @function и т.п. Хорошая документация.
Powered by POEM™ Engine Copyright © 2002-2005