Здравствуйте, c-smile, Вы писали:

CS>Вопрос — я один такой?
CS>Если нет то давайте обсудим как жить дальше.
CS>Что есть такое полезная документация к коду, компоненту и т.д?

POD?...

AndrewVK,

> ПК>Имхо, в этом и есть проблема Doxygen, JavaDoc и т.п. Они приводят к документации как раз примерно такого уровня. Для описания архитектуры и т.п. почти бесполезны.

> Ну, в NDoc кое какие возможности есть + легко прикрутить свои собственные.

А смысл? Имхо, за исключением ссылок на справочную информацию по конкретным компонентам, привязка к Doxygen/JavaDoc/NDoc в плане документирования архитектуры/установки/rationale и т.п. ничего по сравнению с описанием отдельно не дает, только накладывает свои ограничения, которые приходится доблестно преодолевать.

Здравствуйте, Павел Кузнецов, Вы писали:

ПК>А смысл?

Меньше кнопок жать. Плюс NDoc содержит компилятор chm, не нужно дополнительной тулзы. Плюс единый стиль оформления.

ПК> Имхо, за исключением ссылок на справочную информацию по конкретным компонентам, привязка к Doxygen/JavaDoc/NDoc в плане документирования архитектуры/установки/rationale и т.п. ничего по сравнению с описанием отдельно не дает, только накладывает свои ограничения, которые приходится доблестно преодолевать.

Ну вобщем да. Правда и ограничений особых тоже нет. NDoc не особо хуже любого другого компайлера chm.

Здравствуйте, c-smile, Вы писали:


CS>Просто микс фактически трех языков программирования в одном файле
CS>это имхо слишком (C++, macro, HTML/DoxyGenMarkup)

Есть такое ощущение, что это явление временное.
Когда руки дойдут, появятся нормальные редакторы кода которые вместо HTML-ных кракозябр будут выдавать нормальный Rich text.
Главное соблюсти чтобы сами исходники оставались попрежнему в plain text.

Здравствуйте, vladserge, Вы писали:

V>Есть такое ощущение, что это явление временное.
V>Когда руки дойдут, появятся нормальные редакторы кода которые вместо HTML-ных кракозябр будут выдавать нормальный Rich text.

Судя по скриншотам, JetBrain такое для шарпа готовит.

Здравствуйте, c-smile, Вы писали:

CS>Мне кажется что концепт генераторов документации по исходному коду не работает.
CS>Вообще. Ни разу мне не удалось воспользоваться "сгенеряченной" информацией .

Как quick reference (и не более того!) — вполне себе катит. Но с некоторыми оговорками.

CS>Более того: В исходниках с коментариями под Doxygen тоже информацию
CS>потреблять сложно — нужно делать мозговой парсинг каждый раз.

Мое глубокое убеждение — исходник должен оставаться исходником. Референс, собираемый из комментариев, это конечно же хорошо. Но вот эта самая клизьма в виде XML, сводит всю идею на нет. Не хватает только HTML-ной табличной верстки непосредственно в коде.
Итак, цепочка рассуждений.
1. Исходник с комментариями — это прежде всего plain text.
2. Исходник с комментариями — первичен, референс — вторичен (образуется на основе исходника).
3. Исходник читается глазами в том виде, в каком есть.

Следовательно, любые таги и любое XML-like форматирование являются визуальным мусором. Максимум того, что допустимо — это plain-текст, отформатированный по тем же принципам, что и сам код. Если надо каким-то образом помечать аргументы или что-то еще, то эта пометка должна быть легкой-легкой. Почти не заметной. Что-нибудь типа Wiki-форматирования вполне бы подошло, но уж никак не эти блямбы "<param></param>".

А то, что сейчас преподносится от MS и Sun как великое достижение, является не более чем очередной навязанной клизьмой. Я не люблю жить со вставленной клизьмой. Кто-то любит. И даже убеждает всех остальных, как это полезно для здоровья.

Здравствуйте, GlebZ, Вы писали:

GZ>Здравствуйте, c-smile, Вы писали:

GZ>Так писать мне ляниво Все в хедере.

В варианте c-smile определение something также находится в хедере

Здравствуйте, McSeem2, Вы писали:

MS>любые таги и любое XML-like форматирование являются визуальным мусором. Максимум того, что допустимо — это plain-текст, отформатированный по тем же принципам, что и сам код. Если надо каким-то образом помечать аргументы или что-то еще, то эта пометка должна быть легкой-легкой. Почти не заметной. Что-нибудь типа Wiki-форматирования вполне бы подошло, но уж никак не эти блямбы "<param></param>".

А разве теги обязательны? Никогда их не использовал, только для формирования титульной и подобных страниц, но это всё в отдельных файлах лежит обычно.
А так комменты почти как и до доксигена, пара знаков припинания не сильно мешает:

/**
 * Does something. 
 * @warning sometimes craches :-)
 * @return foo value.
 */
int foo(
    int bar    ///< nice parameter.
    );

Не знаю только, кому это больше помогает — мне для понимания кода (?) или дяде, что бы потягивая кофе тыкать мышкой в chm, а в сорцы совсем не заглядывать.

Здравствуйте, gear nuke, Вы писали:

GN>Не знаю только, кому это больше помогает — мне для понимания кода (?) или дяде, что бы потягивая кофе тыкать мышкой в chm, а в сорцы совсем не заглядывать.

Вот и я о том. По моему гораздо проще смотреть коментарии в самой IDE
там еще есть другие фичи типа go to definition и class tree / namespaces.

Здравствуйте, c-smile, Вы писали:

CS>Вот и я о том. По моему гораздо проще смотреть коментарии в самой IDE
CS>там еще есть другие фичи типа go to definition и class tree / namespaces.

Например, в качестве тултипов очень хорошо помогает. Единственное, с чем я не согласен — так это с способом активации этой подсказки. Способ с наведением курсора мыши работает для кнопок-пимпок, но в исходном коде он является крайне невнятным и неудобным. Нужен клавиатурный способ, например, Alt-Up.

Здравствуйте, AndrewVK, Вы писали:

V>>Есть такое ощущение, что это явление временное.
V>>Когда руки дойдут, появятся нормальные редакторы кода которые вместо HTML-ных кракозябр будут выдавать нормальный Rich text.

AVK>Судя по скриншотам, JetBrain такое для шарпа готовит.

А можно их привести? Что-то сайте jetbrains не видать.

Здравствуйте, c-smile, Вы писали:

Пойду от противного: почему это работает для меня.

1. Наличие опций SOURCE_BROWSER и INLINE_SOURCES делают из документации отличный браузер для кода. Лично для меня удобнее кликать по линкам в html или chm, при этом сразу просматривая код, чем плодить кучу окошек с исходниками в студии или еще где.
2. HTMLHelp — он есть! Со всеми индексами и поисками — только hhc.exe подавай.
3. Примеры использования также можно вставить — примеры здесь и здесь.

Ну и просто мысли.

Doxygen-документация, если ее пишете вы — она в первую очередь для пользователей вашей библиотеки, а уж потом для вас. И если вам лично она не нужна, то как насчет пользователей? Если же вы ее не пишете, то это уж как вам удобнее... Мне бы, например, разбираться с поделием под названием sipXtackLib без Doxygen'а с включенными SOURCE_BROWSER и INLINE_SOURCES было бы ой как лениво...

Документируя архитектуру, стараются обычно не сильно детализировать используемые абстракции. Благо, что это можно сделать на уровне модулей/пространств имен. То есть, под ссылку с названием "архитектура" можно положить достаточно высокоуровневую картинку, нарисованную в каком-нибудь Visio (при этом я предполагаю, что картинка, полученная reverse engineering'ом кода, явно избыточна). А документацию на строение отдельных модулей класть в описание соответствующих namespace'ов.

Здравствуйте, McSeem2, Вы писали:

MS>А можно их привести? Что-то сайте jetbrains не видать.

Где то на форуме "Средства разработки" пробегало.

CS>Мне кажется что концепт генераторов документации по исходному коду не работает.
CS>Вообще.

CS>Ни разу мне не удалось воспользоваться "сгенеряченной" информацией .
А почему, собственно?

CS>Более того: В исходниках с коментариями под Doxygen тоже информацию
CS>потреблять сложно — нужно делать мозговой парсинг каждый раз.
Опять же — не тема не раскрыта. Что именно помешало вопринимать информацию?

CS>Вопрос — я один такой?
CS>Если нет то давайте обсудим как жить дальше.

CS>Что есть такое полезная документация к коду, компоненту и т.д?
Ну например наличие javadocs, doxygen. Описание вызовов и примеры
использования.

По моему, большая часть жабских апи снабжены javadocs, и пользоваться
ими приходится довольно часто — это неотъемлемая часть жизни разработчика — особенно
когда начинаешь работать с незнакомым API. Разве информация о том, что метод делает, что
принимает, что возвращает, какие предусловия имеет и какие исключения бросает —
является бесполезной?

Конечно, наличие комментарив в коде может раздражать и визуально его захламлять —
но, ценность в том, что больше шансов что такие комментарии будут изменены при
рефакторинге — чего скорее всего не случится в случае, если описание хранится отдельно
от кода в сводобной форме.

CS>Ок. спасибо. Т.е. все-таки существуют системы в которых doxygen стиль документации работает.
CS>Вопрос: чем обусловлен успех в данном случае? Лучшей поддержкой среды?

Первое что я делаю, когда скачиваю неизвестное API (даже до того, как скачал) — это
смотрю javadocs / doxygen документацию, если она есть. Самый быстрый и понятный способ
оценить сразу дизайн (иногда отсеять явный трэш до скачивания), функционал и отчасти понять,
как пользоваться. Какая среда имеется ввиду? Какая среда нужна для просмотра документации,
кроме браузера?

CS>Гипотеза (личная, sic!): в С# и Java нет деления на .h и .cpp файлы — т.е.
CS>просто нет места где можно собрать документацию компактно. Поэтому
CS>сгененренный аннотированный список методов атрибутов — это собственно и
CS>есть .h файл — место где можно увидеть картину в целом и в компактном виде.

CS>Поправьте меня если я не прав.
IMHO, не прав. Аналог заголовков в жабе — это скорее интерфейсы классов.
Хорошо и правильно, когда они есть, и подробная документация, описывающая
поведение там как раз наиболее уместна — в принципе, когда код перегружен
комментариями, это раздражает.

MS>Следовательно, любые таги и любое XML-like форматирование являются визуальным мусором. Максимум того, что допустимо — это plain-текст, отформатированный по тем же принципам, что и сам код. Если надо каким-то образом помечать аргументы или что-то еще, то эта пометка должна быть легкой-легкой. Почти не заметной. Что-нибудь типа Wiki-форматирования вполне бы подошло, но уж никак не эти блямбы "<param></param>".

Это, безусловно, верно. Но держать эти комментарии в коде — единственный, наверное,
способ добиться их апдейта при изменениях кода, хоть как-то работающий.

Вроде, нормальные редакторы могут эти комментарии либо отображать бледно-серым, либо вообще скрывать —
так, что бы они не навязывались. Это хоть какой-то выход. По поводу wiki-синтаксиса — где-то согласен,
где-то нет. С одной стороны, он менее жирный, что есть хорошо. С другой стороны — он в данном случае
отображает скорее визуальное форматирование, чем модель предметной области — что есть плохо.

Здравствуйте, Alxndr, Вы писали:

A>В варианте c-smile определение something также находится в хедере
Зато реализация в cpp. Тратить столько Джоулей на работу по переключению окон, я неспособен. Лучше я кофе попью на компиляции.

С уважением, Gleb.

Здравствуйте, dmz, Вы писали:

dmz>Это, безусловно, верно. Но держать эти комментарии в коде — единственный, наверное,
dmz>способ добиться их апдейта при изменениях кода, хоть как-то работающий.

Как говорит Алан Голуб в своей древней книжке, надо писать комментарии блоками — блок комментариев, блок кода и т.д. Комментирование каждой строки ужасно сбивает с толку — это все равно, что взять два текста и перемешать строки — строка из одного файла, строка из другого и т.д. А потом читать.

Стиль Doxygen, так же как и JavaDoc приводят имеенно к такому бардаку при описании классов. Исходник становится совершенно нечитаемым. Ну Java и C# сами по себе диктуют такой стиль, поскольку тело метода в том же месте и находится. Это, IMO, тоже плохо с точки зрения понимания общей архитектуры — за деревьями леса не видать. Чаще всего, нам, особенно на начальных этапах изучения, нам глубого пофиг информация о том, что значит каждый параметр и что делает эта функция. Нам важно прежде всего охватить общую концепцию — протокол взаимодействия с этим классом. Но из за обилия кода и комментариев, даже простейший класс раздувается до необозримых величин и становится совершенно нечитаемым. Близким к идеалу было бы что-то типа такого (некий псевдо-C++):

/// Описание класса и протокола взаимодействия с ним
/// ...
class foo
{
public:
   foo();
   void bar();
};

implement class foo
{
   /// Подробное описание конструктора
   /// ...
   foo()
   {
   }

   /// Подробное описание функции
   /// ...
   void bar()
   {
   }
}

В таком виде даже просто исходник безо всяких chm является вполне хорошей документацией. А если еще редактор позволяет подсвечивать информацию о функциях в виде тултипов — это вообще сказка. И исходник остается исходником — вполне целостным и с хорошо локализуемой информацией.

Doxygen вроде бы как позволяет такое делать, но на практике часто затыкается на шаблонах. На Java, C# такое в принципе невозможно, в силу устройства языка. Кроме того, если описание класса компактно, я бы предпочел, чтобы он был приведен в документации как есть, а не порубленный в мелкую крошку.


dmz>Вроде, нормальные редакторы могут эти комментарии либо отображать бледно-серым, либо вообще скрывать —
dmz>так, что бы они не навязывались. Это хоть какой-то выход. По поводу wiki-синтаксиса — где-то согласен,
dmz>где-то нет. С одной стороны, он менее жирный, что есть хорошо. С другой стороны — он в данном случае
dmz>отображает скорее визуальное форматирование, чем модель предметной области — что есть плохо.

Я же не сказал Wiki. Я сказал типа Wiki. Да даже TeX подошел бы.

/// \par{Параметр ля-ля-ля}
/// \ret{Возвращает такой-то результат}

Точнее сказать, описание параметров и прочие наиболее частые сущности надо оставить как в Doxygen "@param" — или как там? А для более продвинутых сущностей (формул и даже рисунков!) использовать TeX-like. Но самое главное — чтоб без фанатизма. Такст должен хорошо читаться не только после обработки, но и сам по себе. И никаких издевательств в виде XML!

И вообще, чаще нужен не Doxygen, а просто хорошо-кросс-линкованный HTML исходников. Вот, например:
http://antigrain.com/demo/alpha_mask2.cpp.html
Сделано с помощью AGDoc
Там не очень-то много чего линкуется, фактически только классы, структуры, енумы и т.д. Но зато совершенно не зависит от языка. А распарсить C++ — это вам не фунт изюму. Doxygen плоховато справляется.

Здравствуйте, McSeem2, Вы писали:

Маленькое замечание по поводу вот этого:

MS>....Комментирование каждой строки ужасно сбивает с толку — это все равно, что взять два текста и перемешать строки — строка из одного файла, строка из другого и т.д....

Я считаю, что это неверная аналогия. Комментарии, которые мне кажутся правильными, будут не "другим текстом", а дополнение к тексту программы. Т.е., та информация, которую нельзя выразить явно кодом — мы ее выражаем комментариями.
Типа

x = 1765; //magic number, source is bla-bla-bla;

//param value must be in [-100..200] range
int foo(in param);

и т.п.
Все остальное должен сообщать сам код.
"Я так думаю".

Здравствуйте, Зверёк Харьковский, Вы писали:

ЗХ>Я считаю, что это неверная аналогия. Комментарии, которые мне кажутся правильными, будут не "другим текстом", а дополнение к тексту программы. Т.е., та информация, которую нельзя выразить явно кодом — мы ее выражаем комментариями.
ЗХ>Типа
ЗХ>

ЗХ>x = 1765; //magic number, source is bla-bla-bla;

ЗХ>//param value must be in [-100..200] range
ЗХ>int foo(in param);
ЗХ>

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

    class stroker
    {
        . . .
        // Stroke parameters
        void line_cap(line_cap_e lc);
        void line_join(line_join_e lj);
        void inner_join(inner_join_e ij);
        void width(double w);
        void miter_limit(double ml);
        void approximation_scale(double as);
        void shorten(double s);
        . . .
    };

Здесь мы просто-напросто приводим список методов, как оглавление. А подробное описание должно быть где-то еще, перед имплементациями методов. И оно должно высвечиваваться в отформатированном виде в качестве тултипов.