QDoc 경고를 해결하는 방법

QDoc은 문서 세트를 생성할 때 경고를 발행할 수 있습니다. 이 섹션에서는 이러한 경고의 의미와 해결 방법을 설명합니다. 이 문서에서는 Clang에서 생성된 경고에 대해서는 설명하지 않습니다.

<대상>에 연결할 수 없음

이 경고는 문서의 한 부분(경고 메시지에서 식별됨)이 다른 부분을 참조하려고 하지만 링크의 대상인 다른 부분을 올바르게 지정하지 않은 경우 QDoc에서 발행합니다. 참조가 잘못 입력되었거나 대상의 이름(함수나 유형의 경우) 또는 제목(다른 섹션의 경우)이 변경되었기 때문에 이 문제가 발생할 수 있습니다.

해당 특정 링크 대상의 소스 코드를 검색합니다. 검색 결과가 나오지 않으면 일치하는 항목을 찾을 때까지 점차 검색 범위를 좁혀보세요.

링크 대상이 유형이나 함수의 이름처럼 보이는 경우도 그 원인일 수 있습니다:

• 문서화된 곳에서 사용된 이름(또는 함수의 경우 지정된 경우 서명)이 선언에 사용된 이름과 일치하지 않는 경우.
• 링크 텍스트가 아닌데 링크 대상이 \internal로 표시된 경우.

테이블의 테이블 항목 외부에서 \target 명령을 발견했습니다.

QDoc에서 \table ... 테이블 끝 블록 내에 있는 \target 명령을 발견하면 이 경고를 표시합니다. 이 경고 뒤에는 이 경고를 해결하려면 \li 내에서 \target을 이동하십시오라는 텍스트가 표시됩니다.

인용할 코드 조각 파일을 찾을 수 없습니다.

QDoc은 \snippet 또는 \quotefromfile 명령의 이름을 딴 파일을 찾을 수 없는 경우 이 경고를 표시합니다.

이 문제를 해결하는 데 유용한 몇 가지 단계가 있습니다:

• 코드조각 파일 이름이 올바른지 확인합니다. QDoc은 검색 경로에 지정된 각 디렉터리에 코드조각 파일 이름을 추가하여 찾을 후보 파일의 경로 이름을 얻습니다. 이러한 후보 파일이 존재하지 않으면 이 오류가 발생합니다.
• *.qdocconf 파일의 exampledirs 구성 변수에 지정된 스니펫의 검색 경로를 확인하세요. 이 경로에 항목을 추가하거나 기존 항목을 수정해야 할 수도 있습니다.
• 스니펫 파일이 존재하는지 또는 QDoc에서 인용하려는 소스 코드에 변경 사항이 있을 때 발생할 수 있는 이동, 이름 변경 또는 제거되었는지 확인합니다.

예기치 않은 \스니펫

QDoc은 \스니펫 명령에서 인용된 스니펫 파일을 찾을 수 없는 경우 이 경고를 표시합니다.

<유형> 또는 그 멤버가 참조하는 문서화되지 않은 QML <모듈>

QDoc은 QML 유형과 연결된 \inqmlmodule 또는 \qmlproperty 명령에 전달된 식별자를 기반으로 QML 모듈을 찾을 수 없는 경우 이 경고를 발행합니다.

이는 \qmlmodule에 대한 설명서가 누락되었거나 \qmlproperty, \qmlmethod 또는 \qmlsignal 명령에 잘못된 모듈 식별자가 사용되었음을 의미합니다.

QML <모듈>에 해당 <유형>이 없습니다.

QDoc은 \qmlproperty, \qmlmethod 또는 \qmlsignal 명령 인수가 QML 모듈 식별자를 사용하지만 연결된 \qmltype이 해당 모듈에 속하지 않는 경우 이 경고를 발행합니다.

QML 모듈 식별자가 정의되어 있는 경우, 이 식별자는 QML 유형 설명서의 \inqmlmodule 인수와 일치해야 합니다. 대부분의 경우 QDoc은 모듈 식별자 없이도 QML 유형을 찾을 수 있습니다.

문서화되지 않은 반환 값

반환 유형이 무효가 아닌 함수의 경우 QDoc은 반환 값이 문서화되어 있는지 확인합니다. 함수 또는 메서드에 대한 문서에 "return"으로 시작하는 단어가 포함되어 있지 않으면 이 경고가 표시됩니다.

문서화되지 않은 매개변수

QDoc은 모든 매개 변수를 설명하기 위해 함수 또는 메서드의 문서화를 요구합니다. a 명령 뒤에 나타나는 각 매개 변수 이름(헤더 파일에서 함수 또는 메서드가 선언된 곳에 지정된 대로)을 통해 이를 인식합니다.

함수 오버로드 문서에는 이 요구 사항이 적용되지 않지만, 오버로드에 대한 표시가 \overload 명령으로 오버로드가 표시되고 같은 이름의 문서화된 함수가 존재하는 경우에는 이 요구 사항이 적용되지 않습니다.

그러한 매개 변수 없음

a 명령 뒤에 지정된 매개 변수 이름이 문서화 중인 함수 또는 메서드의 헤더 파일 선언에 지정된 매개 변수와 일치하지 않을 때 QDoc에서 이 경고를 발행합니다.

알 수 없는 매크로

기본 제공 명령이나 사용자 정의 매크로의 이름으로 인식할 수 없는 토큰 뒤에 백슬래시( \)가 있는 경우 QDoc에서 이 경고를 표시합니다. 문자 이스케이프 시퀀스가 포함된 코드를 인용할 때는 코드를 \c{...}로 묶어 이스케이프 시퀀스에 대한 경고를 방지해야 합니다.

fn <서명>을 구문 분석할 때 함수를 찾지 못했습니다.

Clang이 명령 뒤에 오는 함수 서명을 구문 분석할 때 \fn 명령 뒤에 오는 함수 서명을 구문 분석할 때 헤더 파일의 선언과 비교하여 이를 확인합니다. 불일치를 발견하면 이 경고 메시지를 표시합니다.

서명은 정규화된 것이어야 합니다. 일반적인 문제로는 누락되거나 잘못된 템플릿 인수, 반환 유형 또는 const와 같은 한정자가 있습니다.

<ClassName>을 기본 유형으로 문서화된 QML 유형 <TypeName>. <ClassName>을 <OtherClass>로 바꾸기

명령이 \nativetype 명령이 동일한 문서 프로젝트에 속하는 여러 QML 유형 문서 주석에서 동일한 인수와 함께 사용되는 경우 QDoc에서 이 경고를 표시합니다. 이 문제를 해결하려면 각 C++ 클래스에 대해 \nativetype 명령을 한 번만 사용해야 합니다.

이 문서를 다른 문서에 연결할 수 없음

QDoc에서 /*! ... 주제 명령이 없는 /*!*/ 주석이 바로 뒤에 클래스, 함수 또는 속성 정의가 오지 않았습니다. 따라서 주석이 무엇을 문서화하는지 알 수 없습니다.

이 qdoc 주석에 토픽 명령(예: \module, \page)이 없습니다.

QDoc 주석에 토픽 명령이 포함되어 있지 않으면 QDoc은 주석이 무엇을 문서화하는지 알지 못하며 이 경고를 표시합니다. 이 문서를 다른 문서에 연결할 수 없음과 매우 유사하지만 C++ 또는 QML 파일에 없는 주석에만 해당됩니다.

<이름>이 두 번 이상 문서화됨

같은 항목을 문서화하는 두 개의 주석을 발견하면 QDoc에서 이 경고를 발행합니다. 이전에 본 주석의 위치는 경고 세부 정보에 제공됩니다.

예를 들어 함수의 정의 앞에 문서화 주석이 있고 다른 곳에 별도의 \fn 주석이 있는 경우 이 경고가 표시됩니다.

네임스페이스 <이름>이 두 번 이상 문서화됨

이 경고는 문서 집합에 동일한 인수인 <이름>을 가진 \namespace 명령이 포함된 두 개의 주석이 포함되어 있음을 의미합니다.

<이름>은 문서화되어 있지만 네임스페이스 <이름공간>은 어떤 모듈에도 문서화되어 있지 않습니다.

<이름>에 대한 설명서를 찾았지만 <이름>이 문서화되지 않은 네임스페이스에서 선언되었거나 QDoc이 해당 설명서를 찾을 수 없습니다.

이 문제는 <이름 공간>을 문서화하거나 다른 모듈에 이미 문서화되어 있는 경우 이 모듈에 대한 종속성이 있는지 확인하여 해결할 수 있습니다.

의존성 및 {indexes-variable}{indexes}도 참조하세요.

inmodule 명령이 없음

QDoc 주석이 클래스, 네임스페이스 또는 헤더파일을 \inmodule 명령으로 모듈과 연관시키지 않으면 이 경고가 표시됩니다.

QDoc 주석이 다른 엔티티(일반적으로 네임스페이스 또는 클래스)의 멤버가 아닌 엔티티를 설명하는 경우 \relates 또는 \inmodule을 사용하여 더 넓은 컨텍스트와 연관시켜야 합니다. 그렇지 않은 경우 이 경고가 발생합니다.

헤더 파일에서 \<command>로 지정된 <이름>을 찾을 수 없습니다.

이는 QDoc이 헤더 파일에서 <이름>의 선언을 찾을 수 없지만 이를 문서화한다고 주장하는 주석을 찾았음을 의미합니다.

예시:

Cannot find 'Color::Red' specified with '\enum' in any header file.

문서 주석이 열거 형을 설명한다고 주장하지만 QDoc이 헤더 파일에서 해당 열거 형의 정의를 찾지 못했습니다.

이는 다음과 같은 이유 때문일 수도 있습니다:

• <이름> 또는 <명령>의 오타
• 네임스페이스 또는 클래스 접두사가 누락됨
• <이름>이 다른 네임스페이스 또는 클래스로 이동한 경우

<식별자>에 대해 인식할 수 없는 QML 모듈/유형 한정자

qmlproperty 또는 \qmlmethod에 전달된 매개 변수에 어디에도 정의되지 않은 qmlModule::qmlType::식별자 조합이 포함되어 있습니다.

예제:

Unrecognizable QML module/type qualifier for real QtQuick::DragHandler::DragAxis::minimum

DragHandler 에 DragAxis라는 속성이 없습니다.

<이름>에 대한 누락된 속성 유형

qmlproperty 선언에 해당 속성 유형이 누락되었습니다.

qmlproperty 명령은 속성 유형 다음에 속성의 정규화된 이름(즉, 속성이 속한 클래스 이름 뒤에 ::-가 붙은 이름)이 올 것으로 예상합니다.

잘못되었습니다:

\qmlproperty MyWidget::count

정답입니다:

\qmlproperty int MyWidget::count

여러 번 문서화된 QML 속성: <식별자>

QDoc은 정의 바로 앞에 나타나거나 \qmlproperty 명령을 사용하여 동일한 QML 속성을 문서화하는 두 개의 QDoc 주석을 발견할 때 이 경고를 사용합니다.

QML 속성 명령에 <command> 명령이 허용되지 않음

예시:

\qmlproperty real QtQuick.Controls::RangeSlider::first.value
\qmlproperty real QtQuick.Controls::RangeSlider::first.position
\qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition
\qmlsignal void QtQuick.Controls::RangeSlider::first.moved()
\qmlsignal void QtQuick.Controls::RangeSlider::second.moved()

오류 메시지:

Command '\\qmlsignal' not allowed with QML property commands

이 경고는 속성 그룹 문서에만 해당됩니다. QDoc에서는 경로의 마지막 요소가 <그룹>.<프로퍼티>인 속성 그룹을 문서화하기 위해 단일 문서 주석에 여러 개의 qmlproperty 또는 qmlattachedproperty 주제 명령을 사용할 수 있습니다. 다른 토픽 명령을 사용하면 이 경고가 트리거됩니다.

<class>에서 <method>에 대한 기본 함수를 찾을 수 없습니다.

기본 클래스에 지정된 이름과 서명을 가진 가상 메서드가 없는 경우 가상 메서드의 재정의로서 메서드를 문서화하는 데 \reimp가 사용되는 경우 이 경고가 표시됩니다. 재정의하도록 작성된 메서드의 서명이 변경되었거나 더 이상 가상 메서드가 아니기 때문에 이 문제가 발생할 수 있습니다.

잘못된 \reimp; <command>에 대해 문서화된 가상 함수가 없습니다.

이 함수가 재구현하는 함수에 대한 링크를 만들려고 하지만 해당 함수가 문서화되어 있지 않아 링크 대상을 찾을 수 없습니다. 이 이름과 서명을 가진 가상 메서드를 가진 베이스 클래스가 없는 경우에도 이 문제가 발생할 수 있으며, 이는 이름 변경, 서명 변경 또는 베이스가 더 이상 가상으로 선언하지 않아서 발생할 수 있습니다.

<class>가 자체 상속을 시도합니다.

inherits 명령은 QMl 유형이 다른 QML 유형을 상속한다는 것을 문서화하는 데 사용됩니다. 이 경고는 다른 QML 유형이 문서화된 QML 유형과 동일한 경우 발행됩니다.

예제:

\qmltype Foo
\inherits Foo

\네이티브 유형은 \qmltype에서만 허용됨

nativetype 명령은 QML 유형을 문서화하는 QDoc 주석에서만 사용할 수 있습니다.

그룹의 모든 속성은 <이름>과 같은 유형에 속해야 합니다.

QML 속성 그룹을 문서화할 때 주석 블록에 나열된 모든 속성은 동일한 QML 유형에 속해야 합니다.

프로젝트 파일(예: <이름>)을 찾을 수 없습니다.

예제의 소스 디렉터리에서 QDoc은 CMakeLists.txt 라는 이름의 프로젝트 파일 또는 기본 이름이 예제 디렉터리와 일치하는 .pro, .qmlproject 또는 .pyproject 확장자를 가진 파일을 찾아야 합니다. 예를 들어 examples/mymodule/helloworld/helloworld.pro.

인용할 파일을 열 수 없습니다: <파일 이름>

<파일 이름>의 검색 경로는 .qdocconf 파일에서 다음 변수에 의해 정의됩니다: sources, sourcedirs, 및 exampledirs 입니다.

QDoc이 명명된 파일에서 콘텐츠를 검색하도록 지시하는 명령(예: \quotefromfile, \스니펫, \include)에서 명명된 파일을 찾지 못했습니다. 검색 경로에 이름이 지정된 각 디렉터리를 검색합니다. 해당 디렉터리에 이 이름을 가진 파일이 없거나 파일이 발견되었지만 읽을 수 없는 경우 QDoc은 이 경고를 표시합니다. 검색 경로와 <파일 이름>의 조합의 철자가 올바른지, 파일에 대한 읽기 권한이 있는지 확인하세요.

raw 뒤에 형식 이름이 누락됨

raw 명령과 그에 해당하는 \endraw 명령은 원시 마크업 언어 코드 블록을 구분합니다. draw 명령 뒤에는 반드시 형식 이름이 와야 합니다.

매크로는 형식별 정의와 qdoc 구문 정의를 모두 가질 수 없습니다.

출력 형식을 지정하는 \매크로는 일반 정의도 가질 수 없습니다.

이 경고를 트리거하는 구성의 예입니다:

macro.gui = \b
macro.gui.HTML = "<b>\1</b>"

알 수 없는 명령 <이름>

QDoc 주석이 백슬래시 뒤에 QDoc 기본 제공 명령이 아니며 사용자 지정 명령 매크로로 정의되지 않은 토큰을 사용하는 경우 QDoc에서 이 경고를 생성합니다. 명령 이름의 철자를 확인하고, 사용자 지정 명령인 경우 QDoc 구성에 해당 명령을 정의할 수 있는 내용이 포함되어 있지 않은지 확인하세요.

예를 들어 작성자가 백슬래시를 이스케이프하지 않고 C 문자열 종료 문자 '\0' 또는 다른 C 문자열 이스케이프 시퀀스 중 하나(예: '\n' )를 참조했을 때와 같이 QDoc 주석에 인용된 코드로 인해 이 경고가 표시될 수도 있습니다. 백슬래시를 \ 으로 이스케이프하여 문서에 리터럴 백슬래시를 포함하거나 코드 조각을 \c{...} 으로 묶어 백슬래시가 QDoc 명령을 소개하는 것으로 해석되지 않도록 하세요.

중복된 대상 이름 <대상>

이 경고는 \target 또는 \keyword 명령을 사용하여 동일한 매개 변수로 두 개의 대상을 정의하는 경우 발행됩니다. 이러한 명령에 매개변수로 지정된 대상 이름은 고유해야 합니다. 경고 뒤에는 "이전 항목이 여기에 있습니다: [위치]입니다."(여기서 위치에는 파일 이름과 줄 번호가 포함됨)라는 문구가 표시됩니다.

qdoc 포함 파일 <파일 이름>을 찾을 수 없습니다.

QDoc에서 명령에 지정된 include 파일을 찾지 못했습니다. QDoc은 검색 경로에 이름이 지정된 각 디렉터리를 검색합니다. 해당 디렉터리에 이 이름을 가진 파일이 없거나 해당 검색에서 찾은 파일을 읽을 수 없는 경우 QDoc에서 이 경고를 표시합니다. 검색 경로와 <파일 이름>의 조합의 철자가 올바른지, 파일에 대한 읽기 권한이 있는지 확인하세요.

<파일>에서 <태그>를 찾을 수 없습니다.

이는 QDoc이 \include <파일> 또는 {스니펫 명령}{\스니펫} <파일>에서 식별자 <id>를 찾을 수 없음을 의미합니다.

<파일>에서 빈 qdoc 코드 조각 <태그>

코드조각 <태그>가 \스니펫 <파일>에서 발견되었지만 비어 있습니다.

<command> 명령을 중첩할 수 없습니다.

이 경고는 굵게, 기울임꼴, 색인, 링크, 스팬, 아래 첨자, 위 첨자, 텔레타이프, uicontrol, 밑줄과 같은 서식 지정 명령에 관한 것입니다. 서식 명령은 해당 명령이 적용되는 텍스트 내에서 사용할 수 없습니다. 예를 들면 다음과 같습니다:

There is \b{no \b{super-}bold}.
\encode

\section1 Can't use <inner> in <outer>

This warning is issued for commands that cannot be nested.

Example:
\badcode
    \list
        \li \table
            \row \li Hello \li Hi
            \endtable
    \endlist

"'\list'에 '\table'을 사용할 수 없습니다."라는 QDoc 경고가 표시됩니다.

<내부> 앞에 <외부>가 누락됨

몇 가지 예:

• li 명령은 \list 또는 \table의 \row 내에서만 사용할 수 있습니다.
• row 및 \header 명령은 \table 내에서만 사용할 수 있습니다.

예기치 않은 <END_COMMAND>

이 경고는 예를 들어 앞에 \list가 없는 \endlist가 있는 경우 발행됩니다. 이 경고는 쌍으로 오는 모든 명령(예: startFoo/endFoo)에 적용됩니다.

sa에 쉼표 누락

sa 명령에 나열된 제목은 쉼표로 서로 구분해야 합니다.

매크로 <command>에 기본 정의가 없습니다.

QDoc이 매크로를 확장하려고 시도하고 있으며 해당 매크로에 기본 정의가 있을 것으로 예상합니다. 일부 매크로에는 형식별 정의만 있을 수 있습니다.

예:

macro.pi.HTML = "π"    # encodes the pi symbol for HTML output format

그러나 매크로 확장을 위해 형식에 독립적인 매크로가 필요한 경우가 있습니다. 예를 들어 섹션 제목에 매크로를 사용할 수 있지만 기본 정의가 있어야 합니다.

매크로 <매크로>가 너무 적은 인수를 사용하여 호출됨(<많은> 인수를 예상했으나 <소수> 인수를 받음)

주어진 매크로에 주어진 것보다 더 많은 매개변수가 필요합니다. 자세한 내용은 구성에서 매크로의 정의를 참조하세요.

<텍스트>의 불균형 괄호

해당 '()'가 없는 '(')를 가리키거나 그 반대의 경우도 마찬가지입니다.

<이름>에 대한 문서가 없습니다.

예시:

Warning "No documentation for QNativeInterface."

QDoc이 헤더 파일에서 네임스페이스 QNativeInterface 의 선언을 감지하지만 해당 네임스페이스가 문서화된 QDoc 주석을 찾지 못했습니다.

<class>에 해당 열거형 항목 <name>이 없음

예제:

Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
with \enum in any header file.

열거 형을 문서화한 헤더 파일에서 찾을 수 없는 값의 이름을 지정하는 \enum 주석에서 \value 지시어를 발견하면 QDoc에서 이 경고를 발행합니다.

<열거형 목록>에 문서화되지 않은 열거형 항목 <enum>이 있습니다.

<enum list>의 \value 또는 \omitvalue 항목에 헤더 파일의 <enum list> 선언에 명명된 <enum>에 대한 항목이 포함되어 있지 않습니다.

qhp.<프로젝트>.subprojects.<서브프로젝트>.indexTitle을 찾지 못했습니다.

QDoc이 Qt 도움말 프로젝트 구성에서 <subproject>의 색인 페이지로 지정된 페이지의 제목을 찾지 못했습니다.

하위 프로젝트 색인 제목은 현재 문서 프로젝트에 로컬이어야 합니다. 종속성으로 로드된 다른 프로젝트의 페이지 제목을 사용하는 경우에도 이 경고가 표시됩니다.

자세한 내용은 헬프 프로젝트 파일 만들기를 참조하세요.

\생성 목록 <그룹>이 비어 있습니다.

다음은 \generatelist에 대해 가능한 모든 인수에 대한 간략한 개요입니다:

• \생성 목록 주석 예제
• \생성자 목록 주석이 달린 속성
• \생성 목록 클래스 <접두사>
• \생성 목록 클래스별 모듈 <모듈 이름>
• \생성 목록 qmltypesbymodule <모듈 이름>
• \생성 목록 함수 색인
• \생성 목록 법률
• \생성 목록 개요
• \생성자 목록 속성
• \생성 목록 관련

\generatelist <group> 을 지정했는데 그룹에 항목이 포함되어 있지 않거나 \generatelist <group> <pattern> 을 지정했는데 그룹에 패턴과 일치하는 항목이 없는 경우 QDoc에서 이 경고를 표시합니다.

\생성 목록 <그룹> 해당 그룹 없음

generatelist의 인수가 존재하지 않는 그룹인 경우 이 경고가 표시됩니다.

예제:

\generatelist draganddrop

이 문은 드래그앤드롭 그룹에 있는 클래스 또는 QML 유형 목록을 생성합니다. 클래스 또는 QML 유형은 \l {ingroup-command}{\ingroup} draganddrop 명령의 \class 또는 \qmltype 주석에 의해 드래그앤드롭 그룹에 추가됩니다.

이 \ingroup draganddrop 문을 가진 엔티티가 없는 경우 QDoc에서 이 경고 메시지를 발행합니다.

누락된 이미지: <이미지파일>

이미지의 검색 경로가 잘못되었거나 이미지 파일이 존재하지 않습니다.

<대상>에 연결할 수 없음

다양한 원인이 있을 수 있습니다:

• 링크 대상이 QDoc 주제 명령(예: {title-command}{\title})으로 정의되지 않았습니다. <대상>.
• <대상>에 오타가 있습니다.
• 해당 링크 대상이 포함된 문서가 컴파일되지 않았습니다.
• 해당 링크 대상이 포함된 문서가 컴파일 경로에 없는 모듈에 있습니다.
• 링크 대상이 다른 모듈에 있고 해당 모듈에 대한 종속성이 구성에서 설정되지 않았거나 QDoc에서 종속성에 대한 인덱스 파일을 찾지 못했습니다.

<이름> 유형에 대한 QML 가져오기 문을 확인할 수 없습니다.

QML 유형을 문서화하지만 \inqmlmodule 명령을 생략한 경우 QDoc에서 이 경고를 표시합니다. 예제:

Could not resolve QML import statement for type 'ItemSelectionModel'
\encode

Incorrect:
  \badcode
  \qmltype ItemSelectionModel
  \nativetype QItemSelectionModel
  \since 5.5
  \ingroup qtquick-models

Correct:

\qmltype ItemSelectionModel
\nativetype QItemSelectionModel
\inqmlmodule QtQml.Models
\since 5.5
\ingroup qtquick-models

\brief 문이 마침표로 끝나지 않음

brief 명령의 인수는 문서화된 주제를 요약하는 문장이므로 마침표로 끝나야 합니다. 또한 짧아야 합니다.

QtDeclarative가 설치되지 않아 QML을 구문 분석할 수 없음

QDoc은 QML 구문 분석을 지원하지 않고 컴파일된 경우 이 경고를 표시합니다. 사용자 지정 빌드의 QDoc이 아니라면 이 문제가 발생하지 않아야 합니다.

잘못된 정규식 <regex>

일부 QDoc 명령은 정규식을 매개변수로 사용합니다. 이러한 매개 변수로 지정된 텍스트가 유효한 정규식이 아닌 경우, 일반적으로 이스케이프 처리되어야 하는 정규식에서 특수 의미를 가진 문자가 포함되어 있기 때문에 QDoc은 이 경고를 표시합니다.

예시

notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'

\quotefromfile webenginewidgets/notifications/data/index.html
\skipuntil resetPermission

잘못된 정규식입니다:

\printuntil /^})$/

유효한 정규식입니다:

\printuntil /^\}\)$/

printuntil 명령은 오른쪽 중괄호 뒤에 오른쪽 괄호로만 구성된 줄을 만날 때까지 인쇄합니다. 이 경우 중괄호와 괄호는 정규식에서 특별한 의미를 가지므로 이스케이프 처리해야 합니다.

종속성에 대한 여러 인덱스 파일 발견 <indexfile>:<depend>

종속성 <depend>에 대한 인덱스 파일로 <indexfile> 사용

여러 개의 -indexdir 경로가 명령줄 옵션으로 QDoc에 전달되었고, 하나 이상의 경로에 종속성과 일치하는 .index 파일이 포함되어 있습니다. QDoc은 자동으로 최신 타임스탬프가 있는 파일을 선택합니다.

일반적으로 이 경고는 이전 문서 빌드에서 빌드 아티팩트가 남아 있음을 나타냅니다.

종속성 <depend>에 대한 인덱스 파일을 찾을 수 없습니다.

예시:

"QMake" Cannot locate index file for dependency "activeqt"

문서화 프로젝트 QMake가 지정된 인덱스 디렉터리 중 하나에서 activeqt.index를 찾을 수 없습니다. 이 경우 지정된 인덱스 디렉터리는 qmake.qdocconf에 지정됩니다.

종속 모듈이 지정되었지만 인덱스 디렉터리가 설정되지 않았습니다.

QDoc은 명령줄에 하나 이상의 -indexdir 인수를 표시할 것으로 예상했습니다. 이 인수가 없으면 QDoc은 'depends' 구성 변수로 정의된 종속성의 인덱스 파일을 찾을 수 없습니다.

이전 문서 재정의

QDoc은 동일한 엔티티를 설명하는 것으로 보이는 두 개의 주석을 발견하면 이 경고를 표시합니다. 이전에 본 주석의 위치는 경고 세부 정보에 제공됩니다.

인식할 수 없는 목록 스타일 <이름>

\목록은 목록 스타일을 수정하는 단일 숫자 또는 문자를 선택적 인수로 사용할 수 있습니다. 자세한 내용은 {list-command}{\list} 문서를 참조하세요. 인식되지 않는 인수를 사용하면 QDoc에서 이 경고를 표시합니다.

QML 스니펫을 구문 분석할 수 없음: <y> 줄, <x> 열에 <코드>가 있습니다.

QDoc 주석에는 QML 코드가 포함될 수 있습니다. 이 코드는 코드 조각 또는 \qml 및 {endqml-command}{\endqml}로 구분된 QDoc 주석에서 찾을 수 있습니다.

예:

QML 코드에 구문 오류가 있는 경우 QDoc은 다음과 같은 경고를 표시합니다.

Unable to parse QML snippet: Syntax error at line 97, column 42

코드 조각에도 QML이 포함될 수 있으며 이 코드도 검사됩니다. 예를 들어 코드에 중괄호가 누락된 경우 QDoc은 다음과 같은 경고를 표시합니다.

Unable to parse QML snippet: Expected token '{' at line 63, column 52

QDoc은 종종 불완전한 QML 코드 조각을 구문 분석하지 못하는데, 이러한 경우 \qml ... \endqml 명령을 \code ... \끝코드로 대체하여 이 경고를 표시하지 않는 것이 좋습니다.

<파일 이름> 파일 끝에서 <command> 명령이 실패했습니다.

예제:

Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".

이 경우 경고는 \스니펫 명령이 끝을 표시할 두 번째 레이블 "//! [2]"를 찾지 못했음을 의미합니다. 이 스니펫 파일에서 해당 스니펫 태그를 찾지 못했음을 의미할 수도 있습니다.

또 다른 예입니다:

Command '\skipto' failed at end of file 'styling/CMakeLists.txt".

skipto + <패턴>은 커서를 해당 패턴이 포함된 다음 줄로 이동합니다. skipto가 해당 패턴을 찾지 못하면 QDoc에서 이 경고를 표시합니다.

쓰기 위해 <파일>을 열지 못했습니다.

이 경고는 잘못된 경로 또는 특정 디렉터리에 대한 쓰기 권한으로 인해 쓰기 위해 파일을 열 수 없음을 의미합니다.

이 페이지 제목이 둘 이상의 파일에 존재합니다.

title 명령은 페이지의 제목을 설정합니다.

\page activeqt-server.html
\title Building ActiveX servers in Qt

특정 제목이 두 개 이상의 페이지에서 사용되는 경우 QDoc에서 이 경고를 표시합니다.

콘텐츠가 너무 깁니다.

QDoc은 소스 파일을 토큰화할 때 고정 크기 버퍼를 사용합니다. 파일의 단일 토큰에 최대 제한보다 많은 문자가 있는 경우 QDoc은 이 경고를 표시합니다.

QDoc이 파일을 계속 구문 분석하는 동안 버퍼에 맞는 토큰 부분만 고려되므로 출력이 엉망이 될 수 있습니다.

이 경고를 해결하려면 가능한 경우 관련 콘텐츠를 분할하거나 일부 부분을 제거하여 크기를 줄여야 합니다.

예를 들어 단일 토큰의 최대 글자 수는 경고와 함께 표시됩니다:

file.qdoc:71154: (qdoc) warning: The content is too long.

[The maximum amount of characters for this content is 524288.
Consider splitting it or reducing its size.]

전역 범위에서 <이름> 함수에 대해 생성된 문서가 없음

QDoc이 <name> 함수에 대한 설명서를 선언과 일치시킬 수 있었지만 함수가 전역 네임스페이스에 선언되어 있기 때문에 출력이 생성되지 않았습니다.

관련 명령을 사용하여 함수를 문서화된 유형, 네임스페이스 또는 헤더 파일과 연결합니다. 그러면 함수는 관련 참조 페이지에 관련 비회원으로 나열됩니다.

<프로젝트>에 대한 문서 구성이 도움말 프로젝트를 정의하지 않음(qhp)

유효한 Qt 도움말 구성이 예상되었지만 프로젝트의 .qdocconf 파일에 제공되지 않았습니다.

도움말 프로젝트 파일 만들기 및 qhp를 참조하십시오.

이 프로젝트에 대해 이미 생성된 파일

프로젝트에 대한 문서를 생성하는 동안 QDoc은 생성한 파일의 파일 이름을 추적합니다. 현재 실행 중인 파일이 이전에 생성된 것으로 알려진 경우 QDoc은 쓰기 위해 파일을 열 때 경고를 표시합니다. 이는 다음과 같은 경우 발생할 수 있습니다. \page 명령이 \group 와 같은 이름을 사용하는 경우 발생할 수 있습니다.

환경 변수 QDOC_ALL_OVERWRITES_ARE_WARNINGS 를 설정하여 이러한 모든 이벤트에 대해 무조건 경고하도록 할 수 있습니다. 이는 문제가 되는 정의를 추적할 때 유용할 수 있습니다.