Мне кажется что концепт генераторов документации по исходному коду не работает.
Вообще. Ни разу мне не удалось воспользоваться "сгенеряченной" информацией .
Более того: В исходниках с коментариями под Doxygen тоже информацию
потреблять сложно — нужно делать мозговой парсинг каждый раз.
Вопрос — я один такой?
Если нет то давайте обсудим как жить дальше.
Что есть такое полезная документация к коду, компоненту и т.д?
Здравствуйте, c-smile, Вы писали:
CS>Мне кажется что концепт генераторов документации по исходному коду не работает. CS>Вообще. Ни разу мне не удалось воспользоваться "сгенеряченной" информацией .
Не, меня твои выводы в очередной раз порадовали. Раз у тебя не вышло, значит вобще не работает. А ничего, что референс и по джаве и по .NET (и по львиной доле известных мне коммерческих библиотек для .NET) генерится автоматически?
... << RSDN@Home 1.2.0 alpha rev. 615 on Windows XP 5.1.2600.131072>>
CS>Мне кажется что концепт генераторов документации по исходному коду не работает. CS>Вообще. Ни разу мне не удалось воспользоваться "сгенеряченной" информацией .
не знаю, как по C++, но генерируемой документацией по C#-классам довольно удобно пользоваться.
CS>>Мне кажется что концепт генераторов документации по исходному коду не работает. CS>>Вообще. Ни разу мне не удалось воспользоваться "сгенеряченной" информацией .
DG>не знаю, как по C++, но генерируемой документацией по C#-классам довольно удобно пользоваться.
Ок. спасибо. Т.е. все-таки существуют системы в которых doxygen стиль документации работает.
Вопрос: чем обусловлен успех в данном случае? Лучшей поддержкой среды?
Гипотеза (личная, sic!): в С# и Java нет деления на .h и .cpp файлы — т.е.
просто нет места где можно собрать документацию компактно. Поэтому
сгененренный аннотированный список методов атрибутов — это собственно и
есть .h файл — место где можно увидеть картину в целом и в компактном виде.
Поправьте меня если я не прав.
Еще раз для тех кто в танке — все вышеизложенное есть мое личное мнение.
CS>Гипотеза (личная, sic!): в С# и Java нет деления на .h и .cpp файлы — т.е. CS>просто нет места где можно собрать документацию компактно. Поэтому CS>сгененренный аннотированный список методов атрибутов — это собственно и CS>есть .h файл — место где можно увидеть картину в целом и в компактном виде. CS>Поправьте меня если я не прав.
Сгенерированная документация — обычно удобнее, чем h-ник, т.к. более структурирована.
UML для документирование быстро устаревает, и рассинхронизируется с кодом.
Код, достаточно сложен чтобы о нем говорить как о единственном справочнике. Нужно еще и по русски(английски) некоторую информацию писать.
Здравствуйте, c-smile, Вы писали:
CS>Здравствуйте, DarkGray, Вы писали:
CS>Гипотеза (личная, sic!): в С# и Java нет деления на .h и .cpp файлы — т.е. CS>просто нет места где можно собрать документацию компактно. Поэтому CS>сгененренный аннотированный список методов атрибутов — это собственно и CS>есть .h файл — место где можно увидеть картину в целом и в компактном виде. CS>Поправьте меня если я не прав.
Ты пользуешься inline?
У меня просто существует достаточно много хедренных файлов, которых компактными назвать сложно.
Здравствуйте, GlebZ, Вы писали:
CS>>Гипотеза (личная, sic!): в С# и Java нет деления на .h и .cpp файлы — т.е. CS>>просто нет места где можно собрать документацию компактно. Поэтому CS>>сгененренный аннотированный список методов атрибутов — это собственно и CS>>есть .h файл — место где можно увидеть картину в целом и в компактном виде. CS>>Поправьте меня если я не прав. GZ>Ты пользуешься inline?
Да и много.
GZ>У меня просто существует достаточно много хедренных файлов, которых компактными назвать сложно.
А какие проблемы?
// does something...
// returns: true if did somethinginline bool something();
Здравствуйте, 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-овские теги раскрашиваеются, поэтому они сразу из общего текста комментария выделяются.
... << RSDN@Home 1.1.4 stable rev. 510>>
SObjectizer: <микро>Агентно-ориентированное программирование на C++.
Здравствуйте, c-smile, Вы писали:
CS>Вопрос — я один такой? CS>Если нет то давайте обсудим как жить дальше. CS>Что есть такое полезная документация к коду, компоненту и т.д?
Лично мне под VC 6.0 очень помогает Visual Assist X.
При просмотре кода, если не помнишь, что значит та или иная переменная, наводишь на неё указателем мыши, VA высвечивает подсказку, в которой обознаяается тип переменной, как она была инициализирована и комментарий к ней (если ты его написал предварительно).
При этом не надо отрываться от просмотра кода куда-то ещё.
Хотя при описании сложных систем этот метод, наверное, никуда не годится...
Epsilon,
> При просмотре кода, если не помнишь, что значит та или иная переменная, наводишь на неё указателем мыши, VA высвечивает подсказку, в которой обознаяается тип переменной, как она была инициализирована и комментарий к ней (если ты его написал предварительно). > <...> > Хотя при описании сложных систем этот метод, наверное, никуда не годится...
Имхо, в этом и есть проблема Doxygen, JavaDoc и т.п. Они приводят к документации как раз примерно такого уровня. Для описания архитектуры и т.п. почти бесполезны.
Posted via RSDN NNTP Server 2.0 beta
Легче одурачить людей, чем убедить их в том, что они одурачены. — Марк Твен
Здравствуйте, AndrewVK, Вы писали:
AVK>Не, меня твои выводы в очередной раз порадовали. Раз у тебя не вышло, значит вобще не работает. А ничего, что референс и по джаве и по .NET (и по львиной доле известных мне коммерческих библиотек для .NET) генерится автоматически?
На этапе освоения языка (речь о java) или какой-то конкретной библиотеки, я думаю, мало кто пользуется референсом, -- информации мало и она не о том, о чем нужно. Приходится брать туторы и примеры кода (в том числе из туторов). Когда же язык или библиотека более или менее освоен, требуется знать точно, что происходит в том или ином методе некоторого класса. В результате референс опять не нужен, -- достаточно посмотреть исходный текст класса.
Я за собой замечал следующее — если библиотека абсолютно незнакомая, то вначале такая сгенеренная документация просматривается по диагонали, чтобы просто приблизительно ознакомиться со структурой, классами, и тд. А если это уже не первый взгляд, то в случае возникновения каких-нибудь вопросов просто сразу лезу в исходный код — мне так удобнее.
Здравствуйте, A.Lokotkov, Вы писали:
AL>На этапе освоения языка (речь о java) или какой-то конкретной библиотеки, я думаю, мало кто пользуется референсом,
Ну значит я не такой как все. Я пользуюсь.
AL>В результате референс опять не нужен, -- достаточно посмотреть исходный текст класса.
А я вот, уже 4 года программируя под .NET, референсом все равно пользуюсь регулярно.
Здравствуйте, c-smile, Вы писали:
GZ>>UML для документирование быстро устаревает, и рассинхронизируется с кодом. CS>А почему тогда не в отдельном струтризированном документе например HTML?
Тот же недостаток, что и с UML. Рассинхронизация действительности с описаным.
CS>Doxygen — для себя или для того чтобы сказать "документация? а як же!!!" ? CS>Вот в чем вопрос. Глеб можешь привести пример C++ библиотеки у которой хорошая DoxyGen CS>документация. Может я ошибаюсь и есть шастя...
Может и я ошибаюсь. C++ программы у меня не документированы.Так сложилось, что единственным пользователем являюсь я. Поэтому, опыта с данным продуктом нет. А вот на шарповский код — генерю документацию доступную многим.
Здравствуйте, Павел Кузнецов, Вы писали:
ПК>Имхо, в этом и есть проблема Doxygen, JavaDoc и т.п. Они приводят к документации как раз примерно такого уровня. Для описания архитектуры и т.п. почти бесполезны.
Ну, в NDoc кое какие возможности есть + легко прикрутить свои собственные.