Вот подумалось:

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

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

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

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

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

Не, меня твои выводы в очередной раз порадовали. Раз у тебя не вышло, значит вобще не работает. А ничего, что референс и по джаве и по .NET (и по львиной доле известных мне коммерческих библиотек для .NET) генерится автоматически?

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

не знаю, как по C++, но генерируемой документацией по C#-классам довольно удобно пользоваться.

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


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

DG>не знаю, как по C++, но генерируемой документацией по C#-классам довольно удобно пользоваться.

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

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

Еще раз для тех кто в танке — все вышеизложенное есть мое личное мнение.

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

Сгенерированная документация — обычно удобнее, чем h-ник, т.к. более структурирована.

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

UML для документирование быстро устаревает, и рассинхронизируется с кодом.
Код, достаточно сложен чтобы о нем говорить как о единственном справочнике. Нужно еще и по русски(английски) некоторую информацию писать.

Остается "Doxygen, JavaDoc со товарищи..."


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

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

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


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

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

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

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

Да и много.

GZ>У меня просто существует достаточно много хедренных файлов, которых компактными назвать сложно.

А какие проблемы?

// does something...
// returns: true if did something

inline bool something();

Где-нибудь еще:

// something implementation...

inline bool something() { return false; }

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

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

GZ>UML для документирование быстро устаревает, и рассинхронизируется с кодом.
GZ>Код, достаточно сложен чтобы о нем говорить как о единственном справочнике. Нужно еще и по русски(английски) некоторую информацию писать.

А почему тогда не в отдельном струтризированном документе например HTML?

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

GZ>Остается "Doxygen, JavaDoc со товарищи..."

Doxygen — для себя или для того чтобы сказать "документация? а як же!!!" ?
Вот в чем вопрос. Глеб можешь привести пример C++ библиотеки у которой хорошая DoxyGen
документация. Может я ошибаюсь и есть шастя...

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

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

Работают, работают. Причем именно в doxygen и в C++. Постоянно пользуюсь как сгенерированной по собственным исходникам документацией, так и документацией по библиотеке ACE. А раньше пользовался таковой по Crypto++ и по Qt (там, правда, не Doxygen, но Doxygen от Qt-шного стиля многое взял). Кстати, проект KDE как раз успешно Doxygen-ом пользуется.

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

Не сталкивался. Наверное сила привычки и знакомство с LaTeX-ом -- очень похоже получается. Да и у меня в ViM-е doxygen-овские теги раскрашиваеются, поэтому они сразу из общего текста комментария выделяются.

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

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

Лично мне под VC 6.0 очень помогает Visual Assist X.
При просмотре кода, если не помнишь, что значит та или иная переменная, наводишь на неё указателем мыши, VA высвечивает подсказку, в которой обознаяается тип переменной, как она была инициализирована и комментарий к ней (если ты его написал предварительно).

При этом не надо отрываться от просмотра кода куда-то ещё.
Хотя при описании сложных систем этот метод, наверное, никуда не годится...

Epsilon,

> При просмотре кода, если не помнишь, что значит та или иная переменная, наводишь на неё указателем мыши, VA высвечивает подсказку, в которой обознаяается тип переменной, как она была инициализирована и комментарий к ней (если ты его написал предварительно).
> <...>
> Хотя при описании сложных систем этот метод, наверное, никуда не годится...

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

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

AVK>Не, меня твои выводы в очередной раз порадовали. Раз у тебя не вышло, значит вобще не работает. А ничего, что референс и по джаве и по .NET (и по львиной доле известных мне коммерческих библиотек для .NET) генерится автоматически?

На этапе освоения языка (речь о java) или какой-то конкретной библиотеки, я думаю, мало кто пользуется референсом, -- информации мало и она не о том, о чем нужно. Приходится брать туторы и примеры кода (в том числе из туторов). Когда же язык или библиотека более или менее освоен, требуется знать точно, что происходит в том или ином методе некоторого класса. В результате референс опять не нужен, -- достаточно посмотреть исходный текст класса.

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

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

Для генерации Reference такие вещи ну просто лучше не придумаешь.

Другое дело что в документации должны быть и другие разделы:
Getting Started, HowTo, Installation....

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

AL>На этапе освоения языка (речь о java) или какой-то конкретной библиотеки, я думаю, мало кто пользуется референсом,

Ну значит я не такой как все. Я пользуюсь.

AL>В результате референс опять не нужен, -- достаточно посмотреть исходный текст класса.

А я вот, уже 4 года программируя под .NET, референсом все равно пользуюсь регулярно.

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

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

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

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

GZ>>UML для документирование быстро устаревает, и рассинхронизируется с кодом.
CS>А почему тогда не в отдельном струтризированном документе например HTML?
Тот же недостаток, что и с UML. Рассинхронизация действительности с описаным.

CS>Doxygen — для себя или для того чтобы сказать "документация? а як же!!!" ?
CS>Вот в чем вопрос. Глеб можешь привести пример C++ библиотеки у которой хорошая DoxyGen
CS>документация. Может я ошибаюсь и есть шастя...
Может и я ошибаюсь. C++ программы у меня не документированы.Так сложилось, что единственным пользователем являюсь я. Поэтому, опыта с данным продуктом нет. А вот на шарповский код — генерю документацию доступную многим.

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

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

DG>Сгенерированная документация — обычно удобнее, чем h-ник, т.к. более структурирована.

И по ней есть поиск и индекс, что тоже немаловажно.

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

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

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