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의 작동 방식

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

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

모든 헤더 파일을 파싱하고 문서화할 항목의 마스터 트리를 구축한 후, QDoc은 sourcedirs 변수 및/또는 sources 변수의 값을 사용하여 프로젝트의 모든 .cpp 및 .qdoc 파일을 찾아 파싱합니다. 이 파일들이 바로 QDoc이 QDoc 주석을 검색하는 대상입니다. QDoc 주석은 느낌표(! )로 시작한다는 점을 기억하십시오: /*!.

QDoc 주석을 하나씩 찾을 때마다, 마스터 트리에서 해당 문서가 속한 항목을 검색합니다. 그런 다음 주석 내의 QDoc 명령어를 해석하고, 해석된 명령어와 주석 텍스트를 해당 항목의 트리 노드에 저장합니다.

마지막으로, QDoc은 마스터 트리를 탐색합니다. 각 노드에 대해, 해당 노드에 문서가 저장되어 있는 경우 QDoc은 outputformats 변수로 지정된 출력 생성기를 호출하여 문서를 서식화하고, 구성 파일의 outputdir 변수에 지정된 디렉터리에 문서를 기록합니다.

명령어 유형

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

• 주제 명령어
• 컨텍스트 명령어
• 마크업 명령어

주제 명령어는 문서화하는 요소(예: C++ 클래스, 함수, 유형 또는 기본 C++ 요소와 매핑되지 않는 추가 텍스트 페이지)를 식별합니다.

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

마크업 명령어는 문서 내의 텍스트 및 이미지 요소가 어떻게 렌더링되어야 하는지, 또는 문서의 개요 구조에 대한 정보를 QDoc에 알려줍니다.