Russian Qt Forum

Qt => Общие вопросы => Тема начата: QCasper от Октябрь 28, 2008, 16:43



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


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


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: QCasper от Октябрь 28, 2008, 16:51
Где-то я читал, что у них своя генериловка документации.

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


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: BRE от Октябрь 28, 2008, 16:54
Но уж слишком большое сходство с доксигеном. А в доках по доксигену постоянно упоминается "Qt style".
Возможно они doxygen напильником...


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: lit-uriy от Октябрь 28, 2008, 16:55
документация Qt сгенрирована с помощью qdoc, из которого вырос Doxygen, автор qdoc ушел из трольтеха давно.
для версии Qt4.4.x qdoc лежит в каталоге %QTDIR%\tools\qdoc3


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: lit-uriy от Октябрь 28, 2008, 16:57
по проблеме:
Я не уверен что кусок выдерается, троли хранят снипеты отдельно
%QTDIR%\doc\src\snippets

Если ты собираешся пользоватся qdoc3, то бойся с русским языком есть проблемы, я почти все вычистил осталась только движка Java, там фраза "See also" не поддается. Они все к латин 1 приводят в этом проблема, обсуждалось здесь (http://www.forum.crossplatform.ru/index.php?showtopic=284&view=findpost&p=2855)


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: QCasper от Октябрь 28, 2008, 17:01
по проблеме:
Я не уверен что кусок выдерается, троли хранят снипеты отдельно
%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;
 };


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: lit-uriy от Октябрь 28, 2008, 17:03
2 QCasper, да видимо так, я подправил свой пост, на случай если ты решишь использовать qdoc3


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: lit-uriy от Октябрь 28, 2008, 17:09
есть еще косячек с русским языком при ключе \title см. тут (http://www.forum.crossplatform.ru/index.php?showtopic=551)


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: vregess от Октябрь 28, 2008, 18:31
документация Qt сгенрирована с помощью qdoc, из которого вырос Doxygen, автор qdoc ушел из трольтеха давно.
для версии Qt4.4.x qdoc лежит в каталоге %QTDIR%\tools\qdoc3

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


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


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: QCasper от Октябрь 29, 2008, 09:21
многое выкинул, видимо и snipet'ы тоже

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


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: lit-uriy от Октябрь 29, 2008, 10:00
2 QCasper, см.
\include <file-name>
\example <file-name>
помоему они вполне решат твою задачу


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: QCasper от Октябрь 29, 2008, 11:11
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();
};


Название: Re: Doxygen, исходники Qt и команда \snippet
Отправлено: lit-uriy от Октябрь 29, 2008, 11:47
Возьму на заметку, спасибо.