외부 코드 포함

다음 명령을 사용하면 외부 파일의 코드 스니펫을 포함할 수 있습니다. 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)에 저장됩니다.

QDoc은 발견한 파일 중 가장 먼저 일치하는 파일을 사용합니다. 동일한 상대 경로가 두 개 이상의 검색 디렉터리에 존재할 경우, QDoc은 사전순 경로 순서대로 디렉터리를 참조하므로, 한 파일이 다른 파일을 가릴 수 있습니다.

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

\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 명령어는 미리 서식이 지정된 텍스트의 빈 줄을 삽입합니다. 이 명령어는 현재 미리 서식이 지정된 텍스트 영역을 닫지 않고도 스니펫 사이에 간격을 삽입할 때 사용됩니다.