Здравствуйте, McSeem2, Вы писали:
MS>Стиль Doxygen, так же как и JavaDoc приводят имеенно к такому бардаку при описании классов. Исходник становится совершенно нечитаемым. Ну Java и C# сами по себе диктуют такой стиль, поскольку тело метода в том же месте и находится. Это, IMO, тоже плохо с точки зрения понимания общей архитектуры — за деревьями леса не видать. Чаще всего, нам, особенно на начальных этапах изучения, нам глубого пофиг информация о том, что значит каждый параметр и что делает эта функция. Нам важно прежде всего охватить общую концепцию — протокол взаимодействия с этим классом. Но из за обилия кода и комментариев, даже простейший класс раздувается до необозримых величин и становится совершенно нечитаемым. Близким к идеалу было бы что-то типа такого (некий псевдо-C++):
<...>
MS>Doxygen вроде бы как позволяет такое делать, но на практике часто затыкается на шаблонах.
Ну, шаблоны со временем подтянутся. Doxygen-то не стоит на месте, развивается постоянно.
MS>Я же не сказал Wiki. Я сказал типа Wiki. Да даже TeX подошел бы.
MS>
MS>/// \par{Параметр ля-ля-ля}
MS>/// \ret{Возвращает такой-то результат}
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
*/ |
Файл Doxygen
# Doxyfile 1.4.3
PROJECT_NAME = Test Project
OUTPUT_LANGUAGE = Russian
EXTRACT_PRIVATE = YES
FILE_PATTERNS = *.dox *.?pp
EXAMPLE_PATH = . |
Еще один реальный пример использования Doxygen для создания не только On-Line Reference, но и описаний, можно найти здесь.... << RSDN@Home 1.1.4 stable rev. 510>>
SObjectizer: <микро>Агентно-ориентированное программирование на C++. | |
Оценить 
