Doxygen, исходники Qt и команда \snippet

[QCasper]

Я полагаю, что документация Qt сгенерирована с помощью Doxygen. Те, кто имели дело с этой штукой, знают, что можно оперировать командами типа \class, \interface и многими другими. Я обнаружил в исходниках Qt команду \snippet, с помощью которой выдирается кусок текста из другого файла и вставляется на место этой команды. Описание этой команды я не нашел в документации по доксигену, и она как есть не работает. Можно предположить, что это какой-то алиас, но его определение я так и не нашел. Если кто-то сталкивался, помогите, пожалуйста, очень нужна подобная команда.

[BRE]

Я полагаю, что документация Qt сгенерирована с помощью Doxygen. Те, кто имели дело с этой штукой, знают, что можно оперировать командами типа \class, \interface и многими другими. Я обнаружил в исходниках Qt команду \snippet, с помощью которой выдирается кусок текста из другого файла и вставляется на место этой команды. Описание этой команды я не нашел в документации по доксигену, и она как есть не работает. Можно предположить, что это какой-то алиас, но его определение я так и не нашел. Если кто-то сталкивался, помогите, пожалуйста, очень нужна подобная команда.

Где-то я читал, что у них своя генериловка документации.

[QCasper]

Где-то я читал, что у них своя генериловка документации.

Но уж слишком большое сходство с доксигеном. А в доках по доксигену постоянно упоминается "Qt style".

[BRE]

Но уж слишком большое сходство с доксигеном. А в доках по доксигену постоянно упоминается "Qt style".

Возможно они doxygen напильником...

[lit-uriy]

документация Qt сгенрирована с помощью qdoc, из которого вырос Doxygen, автор qdoc ушел из трольтеха давно.
для версии Qt4.4.x qdoc лежит в каталоге %QTDIR%\tools\qdoc3

[lit-uriy]

по проблеме:
Я не уверен что кусок выдерается, троли хранят снипеты отдельно
%QTDIR%\doc\src\snippets

Если ты собираешся пользоватся qdoc3, то бойся с русским языком есть проблемы, я почти все вычистил осталась только движка Java, там фраза "See also" не поддается. Они все к латин 1 приводят в этом проблема, обсуждалось здесь

[QCasper]

по проблеме:
Я не уверен что кусок выдерается, троли хранят снипеты отдельно
%QTDIR%\doc\src\snippets

Совершенно верно, сами снипеты хранятся отдельно, но часть кода сниппета оказывается на месте команды. Можете сами посмотреть: возьмем исходник qsignalmapper.cpp, там есть такие строчки:

Код:

Here's the definition of a simple custom widget that has a single
signal, \c clicked(), which is emitted with the text of the button
that was clicked:

\snippet doc/src/snippets/qsignalmapper/buttonwidget.h 0
\snippet doc/src/snippets/qsignalmapper/buttonwidget.h 1

В то время как сам buttonwidget.h выглядит (частично) так:

Код:

//! [0]
class ButtonWidget : public QWidget
{
    Q_OBJECT

public:
    ButtonWidget(QStringList texts, QWidget *parent = 0);

signals:
    void clicked(const QString &text);

private:
    QSignalMapper *signalMapper;
//! [0] //! [1]
};
//! [1]

И в результате, в асистанте мы имеем:

Here's the definition of a simple custom widget that has a single signal, clicked(), which is emitted with the text of the button that was clicked:
 class ButtonWidget : public QWidget
 {
     Q_OBJECT

 public:
     ButtonWidget(QStringList texts, QWidget *parent = 0);

 signals:
     void clicked(const QString &text);

 private:
     QSignalMapper *signalMapper;
 };

[lit-uriy]

2 QCasper, да видимо так, я подправил свой пост, на случай если ты решишь использовать qdoc3

[lit-uriy]

есть еще косячек с русским языком при ключе \title см. тут

[vregess]

документация Qt сгенрирована с помощью qdoc, из которого вырос Doxygen, автор qdoc ушел из трольтеха давно.
для версии Qt4.4.x qdoc лежит в каталоге %QTDIR%\tools\qdoc3

А разве Doxygen вырос не сам по себе?
Вроде qt-шная утилита была не доступна для широких масс раньше.

[lit-uriy]

На сайте автора Doxygena, ссылку сейчас не вспомню, было описание истории, в кратце:
он пришел работать в Qvazar Technology и ему дали задачу сделать систему документирования делал помоему на Perl'е, потом контора перименоавлась в Trolltech, а библиотека стала называтся Qt, когда он уволился, то  трольтехи стали переписывать систему, помоему как раз на Qt'ях. А он их консультировал и продолжил работать над системой, многое выкинул, видимо и snipet'ы тоже. В итоге у него получился Doxygen, конечно исходники он писал заново, но у него была непобедимая штука - готовое представление об алгоритме работы, о том, что нужно, а чего можно и выкинуть.

[QCasper]

многое выкинул, видимо и snipet'ы тоже

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

[lit-uriy]

2 QCasper, см.
\include <file-name>
\example <file-name>
помоему они вполне решат твою задачу

[QCasper]

2 QCasper, см.
\include <file-name>
\example <file-name>
помоему они вполне решат твою задачу

Не совсем. Дело в том, что мне нужно запихнуть не всё содержимое файла, а только его часть, помеченную специальными метками. Впрочем я нашел решение, которое базируется на использовании команд \dontinclude, \skipline и \until. Таким образом можно создать алиас для выдирания двух кусков из файла:

Код:

snippet{3}="\dontinclude \1\n\skipline /*! [\2]\n\until /*! [\2]\n\skipline /*! [\3]\n\until /*! [\3]\n"

При документировании используется таким образом:

Код:

\snippet{signalmapper/someobject.h,0,1}

Итого, если мы имеем файл:

Код:

#ifndef _SOMEOBJECT_H_
#define _SOMEOBJECT_H_

#include <QObject>

/*! [0] */
class SomeObject : public QObject {
	Q_OBJECT
public:
	SomeObject(QObject *parent):QObject(parent) {}

signals:
	void firstSignal();
	void secondSignal();
/*! [0] */

public slots:
	void emitFirstSignal();
	void emitSecondSignal();
};/*! [1] */

#endif

То, используя вышеописанный приём, в документации на выходе получим:

Код:

class SomeObject : public QObject {
        Q_OBJECT
public:
        SomeObject(QObject *parent):QObject(parent) {}

signals:
        void firstSignal();
        void secondSignal();
};

[lit-uriy]

Возьму на заметку, спасибо.