дерево классов и самодокументирование

Александр Петросян (PAF) 09.10.2002 11:59

друзья,
мне кажется, наконец мы с вами набрали критическую массу обсудить важную вещь, и кто-то один/несколько могут собраться и сделать то, что давно пора сделать.

некоторые слышали про javadoc[http://java.sun.com/j2se/javadoc/]. кто-то видел doxygen[http://www.doxygen.org], результат работы которого и общую идею можно посмотреть применительно к исходникам самого parser [http://parser.ru/docs/src/], взгляните на http://parser.ru/docs/src/classString.htm, видите что происходит? имена и комментарии собраны с исходников.

конечно, можно добавить в тот же doxygen анализатор нашего синтаксиса, это один путь.

но я хочу предложить вниманию другую простую идею:
пишем на paser:
берём каталоги[classes, вебпространство], сканируем его на тему .p/.html файлов, рисуем их список и дерево взаимосвязей.
click в файл: вылезает описание класса, список и описание методов. ссылка с имени, ссылка с метода идёт в листинг файла со строками, причём ссылка с имени идёт на #номер строки.

причём текст описаний брать из .p прямо сейчас.
не надо будет запускать внешней программы.
и не будет времени для рассинхронизации исходника и его документации.

вариант синтаксиса:

##этот класс работает с гостевой книгой
##пример использования:
##@code
##$gb[^gb::create[обычная]]
##^gb.form[]
##^gb.maybe-post[]
##@endcode
@CLASS
gb

##конструктор
## @param имя имя гостевой книги
@create[имя]
код

##выводит форму, внимание, важно, чтобы action был таким-то
##@todo тут важно добавить поле X  [этот текст собирается со всех описаний на одну общую страницу]
@form[]
код

…

уверен, это будет полезно всем, задача несложная, кто-нибудь попробует?

---