Re: XML комментарии
От: x-code  
Дата: 24.10.08 12:07
Оценка: -1
Здравствуйте, Alexander G, Вы писали:

AG>Лучшая документация — это сам код. Комментарии для документации читаются не только в документации, но и в коде.

AG>Т.к. документация пишется в комментарии, "DSL" для неё имеет только одно техническое требование: чтобы оставался комментарием в соответствующем языке. Чем проще и читабельнее, тем лучше.
AG>Вот пример правильного комментария для документации.
AG>http://java.sun.com/j2se/javadoc/writingdoccomments/#format
AG>Можно ещё упростить: вместо @param p1 использовать @p1 и писать менее развёрнуто.
AG>XML же просто замусоривает код своим синтаксическим оверхедом, он не самый лучший язык разметки для данного случая. Convert absloutely everything to XML ?

Я вообще считаю этот путь с xml-комментариями в коде неправильным... код замусоривается, да и пригодны такие комментарии только для автоматической генерации статических хелпов. Т.е. только для комментирования готового кода, который долгое время не будет меняться.
У меня давно уже зреет другая идея: в коде пишутся только "ссылки" на комментарии, а сами комментарии живут в отдельных xml/html файлах и образуют доступную для всех разработчиков проекта базу знаний. Пример (для С++, для других языков будет все то же самое )
//[[project1.part2.subpart3.class1.method4]]
void Class1::Method4()
{
 // ..
}

такие комментарии-ссылки подсвечиваются особым образом, и двойной щелчек (или иное действие) на них приводит к загрузке в специальное окно (закладка в нижней области студии — Output, Find Results...) информации, связанной с этим комментарием. Это полноценный html-редактор, там можно редактировать текст комментария , вводить теги для поиска по тегам, ссылаться на другие топики базы знаний и т.д.
Формат комментария еще не определен — возможно, будет так как в примере, может быть просто GUID топика (хотя это совсем не наглядно), там есть некоторые тонкости.

База знаний строится по принципу иерархического дерева с ориентированными на человека именами узлов (в т.ч. на русском языке), с возможностью поиска по тегам (специальная кнопка на тулбаре, специальный диалог поиска, результаты можно отображать в специальной закладке внизу). Дерево должно быть доступно в студии (закладка в области Class View, Solution Explorer...). Двойным щелчком на узле дерева можно перейти в файл и в позицию файла на соответствующий комментарий-ссылку. Так организуется обратная связи "база — код" (что вообще не сделать с помощью автоматически генерируемых хелпов типа doxygen'а !), а база образует гибрид wiki, аутлайнера и именованной иерархической системы bookmark'ов для всего проекта.
Благодаря тому, что отдельные топики и узлы дерева базы хранятся в маленьких html и xml файлах, база полностью пригодна для существования в системе контроля версий, такой как SVN: апдейт скачивает те файлы, которые были закоммичены другими пользователями, а благодаря текстовому формату возможно автоматическое слияние документов.
 
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.