Здравствуйте, McSeem2, Вы писали:
MS>Стиль Doxygen, так же как и JavaDoc приводят имеенно к такому бардаку при описании классов. Исходник становится совершенно нечитаемым. Ну Java и C# сами по себе диктуют такой стиль, поскольку тело метода в том же месте и находится. Это, IMO, тоже плохо с точки зрения понимания общей архитектуры — за деревьями леса не видать. Чаще всего, нам, особенно на начальных этапах изучения, нам глубого пофиг информация о том, что значит каждый параметр и что делает эта функция. Нам важно прежде всего охватить общую концепцию — протокол взаимодействия с этим классом. Но из за обилия кода и комментариев, даже простейший класс раздувается до необозримых величин и становится совершенно нечитаемым. Близким к идеалу было бы что-то типа такого (некий псевдо-C++):
<...> MS>Doxygen вроде бы как позволяет такое делать, но на практике часто затыкается на шаблонах.
Ну, шаблоны со временем подтянутся. Doxygen-то не стоит на месте, развивается постоянно.
MS>Я же не сказал Wiki. Я сказал типа Wiki. Да даже TeX подошел бы. MS>
MS>Точнее сказать, описание параметров и прочие наиболее частые сущности надо оставить как в Doxygen "@param" — или как там? А для более продвинутых сущностей (формул и даже рисунков!) использовать TeX-like. Но самое главное — чтоб без фанатизма. Такст должен хорошо читаться не только после обработки, но и сам по себе. И никаких издевательств в виде XML!
В Doxygen так и есть. Формулы записываются именно в синтаксисе LaTeX (чтобы их обработать на машине должен быть latex, dvips и gs).
Что до аргументов методов, то кроме @param в Doxygen есть еще два классных варианта:
void some_func(
//! Этот комментарий будет описанием аргумента.int param1,
int param2 //!< И этот так же.
)
{ ... }
Вот маленькая иллюстрация того, что можно сделать с Doxygen. Для теста разместите все эти файлы в одном каталоге и запустите doxygen. В подкаталогах html и latex появится сгенерированная документация. Я использовал doxygen 1.4.3.
Файл test.hpp
/*!
\file
\brief Тестовый класс.
*/#if !defined( TEST_HPP )
#define TEST_HPP
namespace test
{
class Test
{
public :
Test();
Test( int v );
int v() const;
void set_v( int v );
private :
int v_;
};
} /* namespace test */#endif
Файл test.cpp
/*!
\file
\brief Тестовый класс.
*/#include"test.hpp"/*!
\brief Пространство имен для размещения тестового класса.
Все основные текстовые классы размещаются в данном пространстве имен.
*/namespace test
{
/*!
\class Test "test.hpp"
\brief Тестовый класс.
Это тестовый класс для проверки возможности описания классов
не в заголовочном файле.
*/
/*!
\var Test::v_
Значение, которое хранится в классе Test.
*/
/*!
\brief Конструктор по умолчанию
Устанавливает \a v_ в ноль.
*/
Test::Test()
: v_( 0 )
{}
/*!
\brief Инициализирующий конструктор.
Назначает \a v_ указанное значение.
*/
Test::Test(
//! Начальное значение для \a v_.int v )
: v_( v )
{}
/*!
\name Getter-/Setter-ы
\{
*/int Test::v() const
{
/*!
\par Thread-safe?
Да.
*/return v_;
}
void Test::set_v( int v )
{
/*!
\par Thread-safe?
Нет.
\attention
В текущей версии не выполняет никаких проверок!
*/
v_ = v;
}
/*! \} */
} /* namespace test */
Файл mainpage.dox
/*!
\page abstract Аннотация
Задача этого теста -- показать возможности Doxygen по созданию
полноценной документации. Толчком к этому послужило обсуждение
на RSDN.ru (<a href="http://rsdn.ru/forum/Message.aspx?mid=1401092">Doxygen, JavaDoc со товарищи...</a>).
В особенности, сообщение <a href="http://rsdn.ru/Users/Profile.aspx?uid=12737">McSeem2</a>
(<a href="http://rsdn.ru/forum/Message.aspx?mid=1405520&only=1">Re[3]: Doxygen, JavaDoc со товарищи...</a>),
в котором он описал, что хотел бы:
- чтобы было меньше бардака, в частности, чтобы описания классов можно
было делать не в декларациях классов (т.е. не в hpp-файлах);
- чтобы оформление комментариев было в TeX-стиле.
Но, на самом деле, в Doxygen все так и есть. Может быть с шаблонами и есть
пока проблемы, но ведь Doxygen развивается. Со временем и шаблоны подтянутся.
*/
/*!
\page install Инсталляция
- Создайте файл test.hpp.
- Создайте файл test.cpp.
- Создайте файл Doxyfile следующего содержания:
\include Doxyfile
- Запустите doxygen (я использовал версию 1.4.3).
- В подкаталогах html и latex будет создана необходимая документация.
*/
/*!
\page desc Описание
Здесь может быть какое-то сложное описание, разбитое на секции,
подсекции и подподсекции.
\section desc_sec1 Секция
Как всегда, в примерах самое сложное -- это написать какой-то
осмысленный текст.
\subsection desc_sec1_subsec Подсекция
Ну вот, опять та же проблема -- не хватает фантации.
\subsection desc_sec1_subsec2 Еще одна подсекция
Здесь вообще ничего не будет, кроме нескольких подподсекций.
\subsubsection desc_sec1_subsec2_1 Мелкое описание
Пример подподсекции.
\subsubsection desc_sec1_subsec2_2 Еще одно мелкое описание
Ну совсем мелкое.
*/
/*!
\mainpage Тестовый проект для демонстрации возможностей Doxygen
Главная задача -- показать, что с помощью Doxygen можно выстраивать
довольно сложную документацию.
\subpage abstract
\subpage install
\subpage desc
*/
Здравствуйте, Зверёк Харьковский, Вы писали:
MS>>....Комментирование каждой строки ужасно сбивает с толку — это все равно, что взять два текста и перемешать строки — строка из одного файла, строка из другого и т.д....
ЗХ>Я считаю, что это неверная аналогия. Комментарии, которые мне кажутся правильными, будут не "другим текстом", а дополнение к тексту программы. Т.е., та информация, которую нельзя выразить явно кодом — мы ее выражаем комментариями.
а как много вещей можно гараздо компактнее, понятнее и изящнее описывать в виде небольших рисунков.( задумчиво так )
Даже сотня строк текста может не оказаться эквивалентной.
Например как описать проявления глюка на пользовательском интерфейсе с которым борется данный уасток кода? Только картинкой снэпшота: было так — полечили — стало так.
Здравствуйте, A.Lokotkov, Вы писали:
AL>Здравствуйте, AndrewVK, Вы писали:
AVK>>Не, меня твои выводы в очередной раз порадовали. Раз у тебя не вышло, значит вобще не работает. А ничего, что референс и по джаве и по .NET (и по львиной доле известных мне коммерческих библиотек для .NET) генерится автоматически?
AL>На этапе освоения языка (речь о java) или какой-то конкретной библиотеки, я думаю, мало кто пользуется референсом, -- информации мало и она не о том, о чем нужно. Приходится брать туторы и примеры кода (в том числе из туторов). Когда же язык или библиотека более или менее освоен, требуется знать точно, что происходит в том или ином методе некоторого класса. В результате референс опять не нужен, -- достаточно посмотреть исходный текст класса.
Ну и зачем каждый раз смотреть исходник класса, если мне только требуетс уточнить семантику, например, второго параметра в String::Substr(), который иной, чем в Java?
Я активно пользуюсь и тем и другим, в исходники в основном лезу, когда возникают "непонятные" моменты, а за каждым чихом в исходники лазить элементарно долго.
Что касается текущего проекта, то мы юзаем FAR (не тот, который типа Norton-shell, а тот, который MS Help 1.x и MS Help 2.0 ваяет), и свою автогенеренную доку из NDoc припаиваем прямо к установленному MSDN, и разработчикам всегда доступна справка прямо из редактора кода вижуал студии.
Здравствуйте, xvost, Вы писали:
X>Однако с сожалением надо признать что разработка приостановлена до лучших времен.
И когда эти лучшие времена наступят?
... << RSDN@Home 1.1.4 beta 6a rev. 436>>
Пусть это будет просто:
просто, как только можно,
но не проще.
(C) А. Эйнштейн
Здравствуйте, c-smile, Вы писали:
CS>Ок. спасибо. Т.е. все-таки существуют системы в которых doxygen стиль документации работает. CS>Вопрос: чем обусловлен успех в данном случае? Лучшей поддержкой среды?
Выбором ХМЛ-я в качестве формата. Шучу, но в каждой шутке...
Незнаю как в доксигенах, а в Шарпе все ОК. Просто описал метод и информация уже доступна в подсказках для метода. Ну, а хэлп... в него тоже не сложно вылить. Все выливается в ХМЛ, а там преобразуй его как хочешь.
CS>Гипотеза (личная, sic!): в С# и Java нет деления на .h и .cpp файлы — т.е. CS>просто нет места где можно собрать документацию компактно. Поэтому CS>сгененренный аннотированный список методов атрибутов — это собственно и CS>есть .h файл — место где можно увидеть картину в целом и в компактном виде. CS>Поправьте меня если я не прав.
Хреновое предположение. Темболее что 99% С++-кода так же можно писать в .h-файлах.
CS>Еще раз для тех кто в танке — все вышеизложенное есть мое личное мнение.
А я думал вопрос.
... << RSDN@Home 1.2.0 alpha rev. 618>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
А дальше что? Ну, написал ты этот коментарий. Ведь чтобы его увидить нужно перейти к декларации. А в Шарпе ты наживмшь Ctrl+Shift и плучашь подсказку в которй уже есть текстовое описание не только функции, но и каждого ее параметра. Кстати, подсказки для FCL тоже сделаны с помощью ХМЛ-документации Шарпа.
... << RSDN@Home 1.2.0 alpha rev. 618>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, dmz, Вы писали:
dmz>IMHO, не прав. Аналог заголовков в жабе — это скорее интерфейсы классов. dmz>Хорошо и правильно, когда они есть, и подробная документация, описывающая dmz>поведение там как раз наиболее уместна — в принципе, когда код перегружен dmz>комментариями, это раздражает.
Поведение интерфейсов? Может быть их контракты?
... << RSDN@Home 1.2.0 alpha rev. 618>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, McSeem2, Вы писали:
MS>А то, что сейчас преподносится от MS и Sun как великое достижение, является не более чем очередной навязанной клизьмой. Я не люблю жить со вставленной клизьмой. Кто-то любит. И даже убеждает всех остальных, как это полезно для здоровья.
Твои оскорбительные аналогии уже достали.
Тебе явно по делу сказать нечего вот и бьешся в бессильной злобе видя что всем не твое мнение плевать.
А МС с Саном делают очень просто. Если потребители считают фичу полезной и требуют ее поддрежки, то реализуют ее и поддерживают.
А все кто бьется гловкой об стеночку увидив ХМЛ-коментрии, или Явские просто не очень вменяемые люди, ведь они могут их просто не испоьзовать. Мне чем-то эта ситмуация напоминает выступления дедушек на лавочке. Сидят и во все негодуют, мол "включил вчера телевизор, а там баба голая с мотрел и возмущался". Так и хочется сказать ему "дедунь, ты бы переключил канал то... чай не одни".
В общем, зачем оскорбляя других пытаться навязать им свое мнение? Они считаю это удобным вот и используют.
... << RSDN@Home 1.2.0 alpha rev. 618>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, VladD2, Вы писали:
VD>Твои оскорбительные аналогии уже достали. VD>Тебе явно по делу сказать нечего вот и бьешся в бессильной злобе видя что всем не твое мнение плевать.
Шутку понял. Смешно...
McSeem
Я жертва цепи несчастных случайностей. Как и все мы.
Здравствуйте, VladD2, Вы писали:
VD>А МС с Саном делают очень просто. Если потребители считают фичу полезной и требуют ее поддрежки, то реализуют ее и поддерживают.
Это слегка ошибочное мнение. Пример: не было бы в жабке ни for /each/, ни enum-ов если бы .Net их не клюнул. И никакие бы потребители ничего не сделали. Ибо сантехники считали жабку вершиной совершенства. Оказалось нет — вершина это C# 1. Потом выяснилось, что C# 2. А теперь, похоже, C# 3 А теперь внимание вопрос: сколько потребителей считают полезными лямбды из C# 3?
Здравствуйте, Andrei N.Sobchuck, Вы писали:
ANS>Это слегка ошибочное мнение. Пример: не было бы в жабке ни for /each/, ни enum-ов если бы .Net их не клюнул. И никакие бы потребители ничего не сделали. Ибо сантехники считали жабку вершиной совершенства. Оказалось нет — вершина это C# 1. Потом выяснилось, что C# 2. А теперь, похоже, C# 3 А теперь внимание вопрос: сколько потребителей считают полезными лямбды из C# 3?
Ага. Откуда компания зиппо знала, что людям потребуется столько зажигалок?
Вся разработка платформ — это попытки угадать, что потребуется людям.
Хотя, надо сказать, предварительная работа по выяснению, что не нравится сейчас, тоже проводилась.
Итак, разработчики в каждый момент имеют на руках следующие карты:
— список типичных задач, которые решают их потребители
— список недостатков существующих решений
— список достоинств конкурирующих решений
Последние два пункта ясны как день: выкидывай неудачное и воруй успешное. Лишь бы бюджета хватило, ну и технологические ограничения выполнились.
А вот первое — это как раз попытка угадать, где же там оно у нас это все. Ну вот, к примеру: при написании веб приложения дохрена всего интегрировать надо. Типичный набор: HTML/JS/CSS/С#/XML/SQL. Вот и возникает желание размыть границы.
Вообще сама технология .*SP уже является размытием границ между клиентским и серверным кодом. Во времена CGI все было четко видно: вот у нас код, который выполняется и что-то там в поток выводит. А вот у нас вывод этого кода, который тоже как-то работает, и нуждается в отладке.
А теперь берешь прямо в страничку спец.тег запузыриываешь, и все само происходит.
Остался еще SQL. Опять же — вот у нас код, который строку формирует, вот она эта строка. Уехала на сервер — вернулись какие-то данные.
В третьем шарпе, значит, принесут свет SQL в массы, т.е. в миддл-таер. Теперь мы прямо значит в тексте aspx странички будем писать всякие select и все такое в терминах объектной модели предметной области, заботливый компилятор за нас это все статически проверит, а DLink превратит в нормальный SQL-запрос (кто ж из любит, эти многоэтажные джойны с груп баями?). Красота. И знать не надо, что это лямбдой зовется.
А может к 2011 объявят DLink obsolete и "feature I suspected the very begginning to be too obscure to worth inventing".
1.1.4 stable rev. 510
Уйдемте отсюда, Румата! У вас слишком богатые погреба.
Здравствуйте, Sinclair, Вы писали:
ANS>>Это слегка ошибочное мнение. Пример: не было бы в жабке ни for /each/, ни enum-ов если бы .Net их не клюнул. И никакие бы потребители ничего не сделали. Ибо сантехники считали жабку вершиной совершенства. Оказалось нет — вершина это C# 1. Потом выяснилось, что C# 2. А теперь, похоже, C# 3 А теперь внимание вопрос: сколько потребителей считают полезными лямбды из C# 3? S>Ага. Откуда компания зиппо знала, что людям потребуется столько зажигалок?
Так это если есть попытка угадать. В случае Жабки таких попыток не было и они никаким образом не поощрались. А ведь говорилось о том, что Sun постоянно старается дать людям то, чего люди хотят. Я только на этот один момент и возразил.
Здравствуйте, Andrei N.Sobchuck, Вы писали:
VD>>А МС с Саном делают очень просто. Если потребители считают фичу полезной и требуют ее поддрежки, то реализуют ее и поддерживают.
ANS>Это слегка ошибочное мнение. Пример: не было бы в жабке ни for /each/, ни enum-ов если бы .Net их не клюнул. И никакие бы потребители ничего не сделали. Ибо сантехники считали жабку вершиной совершенства.
А, черт его знает. С одной стороны согласен — МС подтокнул Сан к развитию Явы. Но с другой все же и Сантехники поняли свои ошибки. И подтолкнули его к этому пониманию именно требования пользователей. Жать только что поздновато, и жаль, что не все требования удовлетворяются. Хотя тут и Сантехников понять можно. Все же не все требования разумны, а им нужно делать фичи полезные для большинства. Иначе можно быстро угробить язык.
ANS>Оказалось нет — вершина это C# 1. Потом выяснилось, что C# 2. А теперь, похоже, C# 3 А теперь внимание вопрос: сколько потребителей считают полезными лямбды из C# 3?
"Считают полезными" может и не много. А вот оценят после некоторого времяни использования очень многие. Думаю, все кого нельзя назвать ламером оценят приемущества анонимных методов, а так же краткости и удобства синтаксиса лябд. Кстати, он все же не сокращен до предела. Все же имена параметров остались, что не будет приводить к удивлюнию среднего программиста (я надеюсь). А ведь могли ведь неявные имена использовать.
... << RSDN@Home 1.2.0 alpha rev. 618>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, Andrei N.Sobchuck, Вы писали:
ANS>Так это если есть попытка угадать. В случае Жабки таких попыток не было и они никаким образом не поощрались. А ведь говорилось о том, что Sun постоянно старается дать людям то, чего люди хотят. Я только на этот один момент и возразил.
Все намного проще. Дело не в том, что Сан не стремится угодить потребителю. Дело в том, что всем потребителям не угодишь. И Сан считает, что своей стратегией он угодит наибольшему количеству клиентов. Ну, а то что ты, да и я не являемся их клиентами (или являемся, но не довольны) означает только то, что мы не вписываемся в образ клинтов Сана.
Неужели ты и в самом деле веришь, что Сан делает все назло навязывая частное мнение? Просто их видинее такое. И запросы своих клиентов они воспринимают сквозь призму своего видения.
Погляди как у нас на сайте частенько разгораются баталии на ровном месте. Есть стандарт ХМЛ. Его двигают и Сантехники, и MS, и IBM, и все кому не лень. Но у нас на сайте с завидной регулярностью пытаются смешать ХМЛ с дерьмом и предложить "намного лучшую альтернативу". И что МС с Саном должны прислушиваться вот к таким капризным клиентов небрезгающим любой демагогией и оскорблениями лиш бы доказать, что их каприз — это единственно правильное мнение? Да плевать МС и Сану на таких людей. Их ведь очень незначительный процент. Остальные или стоят на тех же позициях что эти мега-корпорации, или просто слепо верят им.
... << RSDN@Home 1.2.0 alpha rev. 618>>
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, VladD2, Вы писали:
VD>Погляди как у нас на сайте частенько разгораются баталии на ровном месте. Есть стандарт ХМЛ. Его двигают и Сантехники, и MS, и IBM, и все кому не лень. Но у нас на сайте с завидной регулярностью пытаются смешать ХМЛ с дерьмом и предложить "намного лучшую альтернативу". И что МС с Саном должны прислушиваться вот к таким капризным клиентов небрезгающим любой демагогией и оскорблениями лиш бы доказать, что их каприз — это единственно правильное мнение? Да плевать МС и Сану на таких людей. Их ведь очень незначительный процент. Остальные или стоят на тех же позициях что эти мега-корпорации, или просто слепо верят им.
МС до недавнего времени было плевать на Линуса и весь OpenSource вместе взятый.
Теперь отплевываются.
... << RSDN@Home 1.1.4 stable rev. 510>>
SObjectizer: <микро>Агентно-ориентированное программирование на C++.