외부 코드 포함

다음 명령을 사용하면 외부 파일의 코드 스니펫을 포함할 수 있습니다. QDoc에 파일의 전체 내용을 포함하도록 하거나 파일의 특정 부분만 인용하고 다른 부분은 건너뛸 수 있습니다. 후자의 일반적인 용도는 파일을 한 청크씩 인용하는 것입니다.

\quotefile

\quotefile 명령은 인자로 지정된 파일의 전체 내용으로 확장됩니다.

이 명령은 줄의 나머지 부분을 인수의 일부로 간주하므로 파일 이름 뒤에 줄 바꿈이 있는지 확인해야 합니다.

파일의 내용은 모노스페이스 글꼴과 표준 들여쓰기를 사용하여 별도의 단락으로 렌더링됩니다. 코드가 그대로 표시됩니다.

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

버전 6.11부터는 \quotefile 명령과 같은 줄에 대소문자를 구분하지 않는 선택적 인수로 언어를 지정할 수 있습니다. 이는 따옴표로 묶인 텍스트에 영향을 줍니다. \code 명령과 같은 방식으로 따옴표로 묶인 텍스트에 영향을 줍니다.

예를 들어

\quotefile [text] examples/main.cpp

이 명령은 QDoc에 마크업 기능이 없는 소스 코드가 포함된 파일에서 인용할 때 유용할 수 있습니다.

또한 \quotefromfile 및 \code.

\quotefromfile

\quotefromfile 명령은 인용할 인수로 지정된 파일을 엽니다.

이 명령은 줄의 나머지 부분을 인수의 일부로 간주하므로 파일 이름 뒤에 줄 바꿈이 있는지 확인하세요.

이 명령은 연습 명령과 함께 파일에서 일부를 인용할 때 사용하기 위한 것입니다: \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. 이를 통해 파일의 특정 부분을 인용할 수 있습니다.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDoc은 인용하는 파일과 해당 파일의 현재 위치를 기억합니다( \printline 참조). 파일을 '닫기'할 필요가 없습니다.

버전 6.11부터는 \quotefromfile 명령과 같은 줄에 대소문자를 구분하지 않는 선택적 인수로 언어를 지정할 수 있습니다. 이렇게 하면 따옴표로 묶인 텍스트가 \code 명령과 같은 방식으로 따옴표로 묶인 텍스트에 영향을 줍니다.

예를 들어

\quotefromfile [text] examples/main.cpp
\skipto main
\printuntil app(argc, argv)

QDoc은 인용하는 코드 언어도 기억하므로 다음과 같은 명령은 \printline, \printto 및 \printuntil 와 같은 명령은 현재 파일에서 인용하여 새 파일을 읽을 때까지 일관된 스타일의 마크업을 적용합니다.

또한 \quotefile, \code 및 \dots.

\printline

\printline 명령은 현재 위치에서 줄로 확장됩니다.

문서가 소스 파일과 동기화된 상태로 유지되도록 하려면 명령의 인자로 해당 줄의 부분 문자열을 지정해야 합니다. 이 명령은 줄의 나머지 부분을 인수의 일부로 간주하므로 줄 바꿈으로 부분 문자열 뒤에 반드시 줄 바꿈을 넣어야 합니다.

소스 파일의 줄은 모노스페이스 글꼴과 표준 들여쓰기를 사용하여 별도의 단락으로 렌더링됩니다. 코드가 그대로 표시됩니다.

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDoc은 파일을 순차적으로 읽습니다. 현재 위치를 앞으로 이동하려면 \skip. .. 명령 중 하나를 사용할 수 있습니다. 현재 위치를 뒤로 이동하려면 다시 \quotefromfile 명령을 다시 사용하면 됩니다.

하위 문자열 인수가 슬래시로 둘러싸여 있으면 regular expression 로 해석됩니다.

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

(전체 예제 파일...)

정규식 /^\}/는 줄의 처음에 나오는 첫 번째 '}' 문자까지 들여쓰기 없이 QDoc이 인쇄하도록 합니다. /.../는 정규식을 묶고, '^'는 줄의 시작을 의미합니다. '}' 문자는 정규식의 특수 문자이므로 이스케이프 처리해야 합니다.

지정된 부분 문자열 또는 정규식을 찾을 수 없는 경우(즉, 소스 코드가 변경된 경우) QDoc은 경고를 표시합니다.

또한 \printto 및 \printuntil.

\printto

\printto 명령은 현재 위치에서 지정된 하위 문자열이 포함된 다음 줄까지 모든 줄로 확장합니다.

이 명령은 나머지 줄을 인수의 일부로 간주하므로 하위 문자열 뒤에 줄 바꿈이 있는지 확인합니다. 이 명령은 또한 위치 지정 및 인수의 규칙을 \printline 명령과 동일한 위치 및 인수 규칙을 따릅니다.

소스 파일의 줄은 모노스페이스 글꼴과 표준 들여쓰기를 사용하여 별도의 단락에 렌더링됩니다. 코드는 그대로 표시됩니다.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

또한 \printline 및 \printuntil.

\printuntil

\printuntil 명령은 현재 위치에서 지정된 하위 문자열이 포함된 다음 줄까지 모든 줄로 확장합니다.

이 명령은 나머지 줄을 인수의 일부로 간주하므로 하위 문자열 뒤에 줄 바꿈이 있는지 확인합니다. 이 명령은 또한 위치 지정 및 인수의 규칙을 \printline 명령과 동일한 위치 및 인수 규칙을 따릅니다.

\printuntil 을 인자 없이 사용하면 현재 위치에서 따옴표로 묶인 파일의 끝까지 모든 줄로 확장됩니다.

소스 파일의 줄은 모노스페이스 글꼴과 표준 들여쓰기를 사용하여 별도의 단락으로 렌더링됩니다. 코드가 그대로 표시됩니다.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

또한 \printline 및 \printto.

\skipline

\skipline 명령은 현재 소스 파일에서 공백이 아닌 다음 줄을 무시합니다.

Doc은 파일을 순차적으로 읽으며 \skipline 명령은 현재 위치를 이동하는 데 사용됩니다(소스 파일의 한 줄 생략). 위의 파일 위치 지정에 대한 설명을 참조하세요.

이 명령은 나머지 줄을 인수의 일부로 간주하므로 줄 바꿈이 있는 하위 문자열 뒤에는 반드시 줄 바꿈이 있어야 합니다. 이 명령은 또한 인수의 규칙을 \printline 명령과 동일한 인수 규칙을 따르며, 이 명령은 \quotefromfile 명령과 함께 사용됩니다.

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

또한 \skipto, \skipuntil 및 \dots.

\skipto

\skipto 명령은 현재 위치에서 지정된 하위 문자열이 포함된 다음 줄까지 모든 줄을 무시합니다.

QDoc은 파일을 순차적으로 읽으며 \skipto 명령은 현재 위치를 이동하는 데 사용됩니다(소스 파일의 한 줄 또는 여러 줄 생략). 위의 파일 위치 지정에 대한 설명을 참조하세요.

이 명령은 나머지 줄을 인수의 일부로 간주하므로 줄 바꿈으로 하위 문자열을 따라야 합니다.

이 명령은 또한 인수의 규칙을 \printline 명령과 동일한 인수 규칙을 따르며, 이 명령은 \quotefromfile 명령과 함께 사용됩니다.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

또한 \skipline, \skipuntil 및 \dots.

\skipuntil

\skipuntil 명령은 현재 위치에서 지정된 하위 문자열이 포함된 다음 줄까지 모든 줄을 무시합니다.

QDoc은 파일을 순차적으로 읽으며 \skipuntil 명령은 현재 위치를 이동하는 데 사용됩니다(소스 파일의 한 줄 또는 여러 줄 생략). 위의 파일 위치 지정에 대한 설명을 참조하세요.

이 명령은 나머지 줄을 인수의 일부로 간주하므로 줄 바꿈으로 하위 문자열을 따라야 합니다.

이 명령은 또한 인수의 규칙을 \printline 명령과 동일한 인수 규칙을 따르며, 이 명령은 \quotefromfile 명령과 함께 사용됩니다.

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

또한 \skipline, \skipto 및 \dots.

\dots

\dots 명령은 파일을 인용할 때 소스 파일의 일부가 생략되었음을 나타냅니다.

이 명령은 다음과 함께 사용됩니다. \quotefromfile 명령과 함께 사용되며 자체 줄에 명시해야 합니다. 점들은 모노스페이스 글꼴을 사용하여 새 줄에 렌더링됩니다.

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

기본 들여쓰기는 4칸이지만 명령의 선택적 인수를 사용하여 조정할 수 있습니다.

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

또한 \skipline, \skipto 및 \skipuntil.

\snippet

\snippet 명령은 코드 조각이 구문이 강조 표시된 미리 서식이 지정된 텍스트로 그대로 포함되도록 합니다.

각 코드 조각은 해당 코드 조각을 담고 있는 파일과 해당 파일의 고유 식별자에 의해 참조됩니다. 코드 조각 파일은 일반적으로 문서 디렉터리 내의 snippets 디렉터리에 저장됩니다(예: $QTDIR/doc/src/snippets).

예를 들어 다음 문서는 문서 디렉터리의 하위 디렉터리에 있는 파일에 있는 코드 조각을 참조합니다:

\snippet snippets/textdocument-resources/main.cpp Adding a resource

파일 이름 뒤에 오는 텍스트는 해당 스니펫의 고유 식별자입니다. 이는 위의 \snippet 명령에 해당하는 다음 예에서와 같이 관련 스니펫 파일에서 따옴표로 묶인 코드를 구분하는 데 사용됩니다:

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

기본적으로 QDoc은 코드 조각 마커로 //! 을 찾습니다. .pro , .py, .cmake, CMakeLists.txt 파일의 경우 #! 가 감지됩니다. 마지막으로 .html, .qrc, .ui, .xml, .xq 파일에서는 <!-- 가 허용됩니다.

QDoc은 스니펫 마커의 공백 기반 들여쓰기를 스니펫의 최소 콘텐츠 들여쓰기(Qt 매크로, 빈 줄, 전체 줄 주석은 무시)와 비교하여 스니펫 들여쓰기를 정규화합니다. 그런 다음 코드조각 본문의 들여쓰기를 자동으로 더 작은 쪽의 들여쓰기를 해제하여 마커의 위치에 관계없이 생성된 코드가 항상 자연스러운 구조를 유지하도록 합니다. 들여쓰기된 마커는 그대로 유지됩니다.

버전 6.11부터는 \snippet 명령과 같은 줄에 대소문자를 구분하지 않는 선택적 인수로 언어를 지정할 수 있습니다. 이렇게 하면 따옴표로 묶인 텍스트가 \code 명령과 같은 방식으로 인용된 텍스트에 영향을 줍니다.

이 명령의 예제에서는 기본 C++ 마크업 스타일을 재정의하고 대신 일반 텍스트를 출력합니다:

\snippet [text] code.cpp

이 기능은 QDoc에 마크업 기능이 없는 언어를 인용하거나 일반적인 파일 이름이 아닌 파일에서 인용해야 할 때 유용할 수 있습니다.

\codeline

\codeline 명령은 미리 서식이 지정된 텍스트의 빈 줄을 삽입합니다. 이 명령은 현재 미리 서식이 지정된 텍스트 영역을 닫고 새 영역을 열지 않고 스니펫 사이에 간격을 삽입하는 데 사용됩니다.