QDoc 소개

QDoc은 Qt 개발자가 소프트웨어 프로젝트에 대한 문서를 생성하는 데 사용하는 도구입니다. 이 도구는 프로젝트 소스 파일에서 QDoc 주석을 추출한 다음 HTML 페이지 또는 DocBook XML 문서로 서식을 지정하는 방식으로 작동합니다. QDoc은 .cpp 파일과 .qdoc 파일에서 QDoc 주석을 찾습니다. QDoc은 .h 파일에서는 QDoc 주석을 찾지 않습니다. QDoc 주석은 항상 느낌표(!)로 시작합니다.) 예를 들어

/*!
    \class QObject
    \brief The QObject class is the base class of all Qt objects.

    \ingroup objectmodel

    \reentrant

    QObject is the heart of the Qt \l{Object Model}. The
    central feature in this model is a very powerful mechanism
    for seamless object communication called \l{signals and
    slots}. You can connect a signal to a slot with connect()
    and destroy the connection with disconnect(). To avoid
    never ending notification loops you can temporarily block
    signals with blockSignals(). The protected functions
    connectNotify() and disconnectNotify() make it possible to
    track connections.

    QObjects organize themselves in \l {Object Trees &
    Ownership} {object trees}. When you create a QObject with
    another object as parent, the object will automatically
    add itself to the parent's \c children() list. The parent
    takes ownership of the object. It will automatically
    delete its children in its destructor. You can look for an
    object by name and optionally type using findChild() or
    findChildren().

    Every object has an objectName() and its class name can be
    found via the corresponding metaObject() (see
    QMetaObject::className()). You can determine whether the
    object's class inherits another class in the QObject
    inheritance hierarchy by using the \c inherits() function.

....
*/

위의 QDoc 댓글에서 QDoc은 HTML QObject class reference 페이지를 생성합니다.

이 설명서에서는 QDoc 주석의 QDoc 명령을 사용하여 소스 파일에 좋은 문서를 임베드하는 방법을 설명합니다. 또한 명령줄에서 QDoc에 전달할 QDoc 구성 파일을 만드는 방법도 설명합니다.

QDoc 실행하기

QDoc 프로그램의 이름은 qdoc 입니다. 명령줄에서 QDoc을 실행하려면 구성 파일의 이름을 지정합니다:

$ ../../bin/qdoc ./config.qdocconf

QDoc은 .qdocconf 접미사를 QDoc 구성 파일로 인식합니다. 구성 파일은 프로젝트 소스 파일, 헤더 파일 및 .qdoc 파일을 찾을 위치를 QDoc에 알려주는 곳입니다. 또한 QDoc에 어떤 종류의 출력(HTML, DocBook XML...)을 생성할지, 생성된 문서를 어디에 넣을지 알려주는 곳이기도 합니다. 구성 파일에는 QDoc에 대한 다른 정보도 포함되어 있습니다.

QDoc 구성 파일을 설정하는 방법에 대한 지침은 QDoc 구성 파일을 참조하세요.

단일 실행 모드에서 QDoc 실행하기

Qt 5.5부터는 Qt5 문서를 생성하는 데 걸리는 시간을 최대 90%까지 단축하는 새로운 QDoc 실행 방법을 사용할 수 있습니다. QDoc을 실행하는 새로운 방법은 단일 실행 모드입니다. 단일 실행 모드는 현재 표준 모드를 사용하는 Qt5 빌드 시스템에서는 사용할 수 없습니다. 단일 실행 모드는 모듈을 문서화하고 다른 Qt 모듈과 문서를 통합할 때 자주 사용하게 될 QDoc을 직접 실행할 때만 사용할 수 있습니다.

단일 실행 모드에서 QDoc을 실행하려면 명령줄에 -single-exec 을 추가하고 모든 Qt5 모듈의 qdocconf 파일의 파일 경로 목록인 마스터 qdocconf 파일을 QDoc에 전달합니다. 예를 들어

/Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec

master.qdocconf 파일은 처리할 모든 Qt5 모듈의 qdocconf 파일을 나열할 뿐입니다:

/Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf
/Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf
/Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf
/Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf
/Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf
/Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf
/Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf
/Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf
/Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf
/Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf
/Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf
/Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf
/Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf
/Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf
/Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf
/Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf
/Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf
/Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf
/Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf
/Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf
/Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf
/Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf
/Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf
/Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf
/Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf
/Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf
/Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf
/Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf
/Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf
/Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf
/Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf
/Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf
/Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf
/Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf
/Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf
/Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf

표준 모드가 느린 이유

현재 Qt5 빌드 시스템은 Qt5 문서 생성을 위해 QDoc의 단일 실행 모드를 사용하지 않습니다. 표준 모드에서 QDoc을 실행합니다. 표준 모드는 Qt5에서 Qt의 모듈화를 처리하기 위해 Qt4 QDoc을 가장 쉽게 변환할 수 있는 방법이었기 때문에 만들어졌습니다. Qt4에서 QDoc은 모든 Qt4 소스를 한 번 실행하여 Qt용 HTML 문서를 생성했습니다. Qt 문서를 생성하는 동안 Qt4 QDoc은 Qt에 대한 인덱스 파일도 생성했습니다. 이 인덱스 파일은 Qt를 기반으로 하는 다른 소프트웨어 라이브러리/제품에 대한 HTML 문서를 생성하기 위한 후속 QDoc 실행의 입력으로 사용하기 위한 것이었습니다. Qt 인덱스 파일을 통해 QDoc은 다른 라이브러리/제품을 위해 작성된 문서를 Qt4 문서에 연결할 수 있었습니다.

Qt5가 등장했을 때, Qt는 모듈로 나뉘었습니다. 그 이후로 많은 새로운 모듈이 Qt에 추가되었습니다. 5.5 버전 현재, Qt5에는 40개 이상의 개별 모듈이 있으며, 각 모듈은 다른 Qt 모듈의 문서에 링크되는(의존하는) 자체 문서를 가지고 있습니다.

표준 모드에서 QDoc은 각 모듈에 대해 두 번 실행됩니다. 특정 Qt 모듈에 대해 처음 실행되는 QDoc은 모듈의 모든 소스 파일을 구문 분석한 다음 그 정보를 사용하여 모듈의 색인 파일을 생성합니다. 모듈의 인덱스 파일을 준비하기 때문에 준비 단계라고 합니다. 모듈에 대한 두 번째 QDoc 실행도 모듈의 모든 소스 파일을 파싱한 다음 모듈의 문서 페이지를 생성합니다. 이 단계는 모듈의 문서를 생성하기 때문에 생성 단계라고 합니다.

모듈의 문서에는 하나 이상의 다른 Qt 모듈의 문서에 대한 HTML 링크가 포함될 가능성이 높습니다. 예를 들어, 대부분의 Qt5 모듈에는 QtCore 에 있는 문서에 대한 링크가 포함되어 있습니다. 한 Qt 모듈이 다른 Qt 모듈의 문서에 대한 링크를 포함하는 경우, 해당 모듈은 다른 Qt 모듈에 의존한다고 할 수 있습니다. 따라서 QDoc이 해당 모듈에 대한 생성 단계를 실행할 때 해당 모듈의 인덱스 파일도 로드해야 해당 링크를 생성할 수 있습니다.

따라서 Qt 빌드 시스템이 Qt 문서를 생성할 때 먼저 각 모듈에 대해 QDoc을 한 번 실행하여 모든 인덱스 파일을 생성하는 준비 단계를 수행합니다. 그런 다음 각 모듈에 대해 QDoc을 한 번씩 실행하여 생성 단계를 수행하고, 여기서 종속 인덱스 파일을 사용하여 찾은 모든 모듈 간 링크를 포함한 모듈의 문서를 생성합니다. 준비 단계 와 생성 단계 모두 QDoc을 실행할 때마다 모듈에 포함된 모든 소스 파일을 파싱하고, 생성 단계에서는 종속 모듈의 인덱스 파일도 파싱합니다. QDoc 실행 사이에 유지되거나 유지될 수 있는 것은 아무것도 없습니다.

단일 실행 모드가 훨씬 빠른 이유

이름에서 알 수 있듯이 단일 실행 모드는 단일 QDoc 프로세스를 사용하여 모든 Qt5 문서를 생성합니다. 단일 QDoc 프로세스는 여전히 각 모듈에 대해 준비 단계를 수행한 다음 각 모듈에 대해 생성 단계를 수행하지만 몇 가지 차이점이 있습니다. 먼저 마스터 qdocconf 파일을 읽는 것으로 시작합니다. 그런 다음 마스터 목록에서 각 qdocconf 파일을 읽고 각 모듈에 대해 준비 단계를 수행합니다. 준비 단계에서는 모듈의 모든 소스 파일을 구문 분석하여 모듈의 구문 트리를 구축합니다. 그런 다음 모듈의 인덱스 파일이 생성되지만 QDoc은 생성 단계에서 인덱스 파일을 다시 읽지 않습니다. 여기서 중요한 차이점은 인덱스 파일이 생성된 후에도 모듈의 구문 트리가 유지되므로 모든 모듈에 대해 준비 단계가 실행된 후에도 QDoc은 구축한 모든 구문 트리를 보유한다는 것입니다.

그런 다음 QDoc은 생성 단계를 위해 각 모듈을 다시 처리합니다. 그러나 이제 모듈의 구문 트리가 여전히 메모리에 있기 때문에 QDoc은 각 모듈의 소스 파일을 다시 파싱할 필요가 없습니다. 또한 종속 모듈의 인덱스 파일도 다시 읽을 필요가 없는데, 이는 해당 모듈의 구문 트리가 여전히 메모리에 있기 때문입니다. 문서 페이지를 생성하기 위해 각 모듈의 구문 트리를 탐색하는 작업만 남습니다.

따라서 QDoc은 각 소스 파일을 한 번만 구문 분석하고 인덱스 파일을 읽을 필요가 없습니다. 이것이 바로 단일 실행 모드가 표준 모드보다 훨씬 빠른 이유입니다. Qt 빌드 시스템은 결국 단일 실행 모드에서 QDoc을 실행하게 될 것으로 예상됩니다. 그러나 마스터 qdocconf 파일을 변경해야 할 수도 있으므로 위에서 설명한 단일 실행 모드에서 QDoc을 실행하는 방법이 변경될 수 있으므로 이 공간에서 업데이트를 지켜보세요.

QDoc 작동 방식

QDoc은 명령줄에서 지정한 구성 파일을 읽는 것으로 시작합니다. 나중에 사용할 수 있도록 구성 파일의 모든 변수를 저장합니다. 가장 먼저 사용하는 변수 중 하나는 outputformats 입니다. 이 변수는 QDoc이 실행할 출력 생성기를 알려줍니다. 기본값은 HTML이므로 구성 파일에서 outputformats 을 설정하지 않으면 QDoc이 HTML 출력을 생성합니다. 일반적으로 이 출력을 원할 것이지만 대신 DocBook 출력을 얻도록 DocBook을 지정할 수도 있습니다.

다음으로, QDoc은 headerdirs 변수 및/또는 headers 변수의 값을 사용하여 프로젝트의 모든 헤더 파일을 찾아 구문 분석합니다. QDoc은 헤더 파일에서 QDoc 주석을 검색하지 않습니다. 헤더 파일을 구문 분석하여 문서화해야 하는 모든 항목, 즉 QDoc이 QDoc 주석을 찾아야 하는 항목의 마스터 트리를 작성합니다.

모든 헤더 파일을 구문 분석하고 문서화할 항목의 마스터 트리를 만든 후 QDoc은 sourcedirs 변수 값 및/또는 sources 변수 값을 사용하여 프로젝트의 모든 .cpp 및 .qdoc 파일을 찾아 구문 분석합니다. 이 파일들은 QDoc이 QDoc 주석을 찾기 위해 스캔하는 파일입니다. QDoc 주석은 느낌표로 시작한다는 것을 기억하세요: /*! .

QDoc 코멘트를 찾을 때마다 마스터 트리에서 해당 문서가 속한 항목을 검색합니다. 그런 다음 주석에 있는 QDoc 명령을 해석하고 해석된 명령과 주석 텍스트를 해당 항목의 트리 노드에 저장합니다.

마지막으로 QDoc은 마스터 트리를 탐색합니다. 각 노드에 저장된 문서가 있는 경우 QDoc은 outputformats 변수로 지정된 출력 생성기를 호출하여 출력dir 변수의 구성 파일에 지정된 디렉터리에 문서를 포맷하고 씁니다.

명령 유형

QDoc은 세 가지 유형의 명령을 해석합니다:

• 토픽 명령
• 컨텍스트 명령
• 마크업 명령

토픽 명령은 문서화 중인 요소(예: C++ 클래스, 함수, 유형 또는 기본 C++ 요소에 매핑되지 않는 추가 텍스트 페이지)를 식별합니다.

컨텍스트 명령은 문서화 중인 요소가 문서화된 다른 요소(예: 다음 및 이전 페이지 링크, 페이지 그룹에 포함 또는 라이브러리 모듈)와 어떻게 관련되어 있는지 QDoc에 알려줍니다. 컨텍스트 명령은 또한 문서화된 요소에 대한 정보(예: 해당 요소가 스레드에 안전한지, 오버로드되거나 재구현된 함수인지, 더 이상 사용되지 않는지 여부 등)를 QDoc이 소스 파일에서 얻을 수 없는 정보를 제공할 수 있습니다.

마크업 명령은 문서의 텍스트 및 이미지 요소를 렌더링하는 방법이나 문서의 개요 구조에 대해 QDoc에 알려줍니다.