QDoc 경고 문제 해결

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

그룹 내의 모든 속성은 동일한 유형에 속해야 합니다: <name>

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

이 프로젝트에 대해 <파일>이 이미 생성되었습니다

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

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

\brief 문장이 마침표로 끝나지 않는 경우

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

<대상>에 링크할 수 없음

QDoc은 문서의 한 부분(경고 메시지에 명시된 부분)이 다른 부분을 참조하려고 시도하지만, 링크의 대상인 해당 부분을 올바르게 지정하지 못한 경우 이 경고를 표시합니다. 이는 대상에 대한 참조가 잘못 입력되었거나, 대상의 이름(함수나 유형의 경우)이나 제목(다른 섹션의 경우)이 변경되었기 때문일 수 있습니다.

이 문제의 원인은 다양할 수 있습니다:

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

소스 코드에서 해당 링크 대상을 검색해 보십시오. 결과가 나오지 않으면 일치하는 항목을 찾을 때까지 검색 범위를 점차 넓혀가십시오.

링크 대상이 유형이나 함수의 이름처럼 보인다면, 다음 이유 때문일 수도 있습니다:

• 문서화된 위치에서 사용된 이름(함수의 경우, 지정된 시그니처)이 선언에서 사용된 이름과 일치하지 않는 경우입니다.
• 링크 대상이 \internal 로 표시되었으나, 연결 텍스트는 그렇지 않은 경우입니다.

<class>의 <method>에 대한 기본 함수를 찾을 수 없음

\reimp 를 사용하여 메서드를 가상 메서드의 오버라이드로 문서화했을 때, 주어진 이름과 시그니처를 가진 가상 메서드를 가진 기저 클래스가 없는 경우 QDoc은 이 경고를 표시합니다. 이는 오버라이드 대상으로 작성된 메서드의 시그니처가 변경되었거나 더 이상 가상 메서드가 아니기 때문에 발생할 수 있습니다.

어떤 헤더 파일에서도 \<command>로 지정된 <name>을 찾을 수 없음

이는 QDoc이 어떤 헤더 파일에서도 <name>의 선언을 찾을 수 없으나, 이를 문서화한다고 명시한 주석을 발견했음을 의미합니다.

예시:

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

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

이 문제는 다음 이유 때문일 수도 있습니다:

• <name> 또는 <command>의 오타
• 네임스페이스 또는 클래스 접두사가 누락된 경우
• <name>이 다른 네임스페이스나 클래스로 이동한 경우

예제 <name>에 대한 프로젝트 파일을 찾을 수 없습니다.

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

인용할 스니펫 파일을 찾을 수 없습니다

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

이 문제를 해결하기 위한 유용한 단계는 다음과 같습니다:

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

qdoc 포함 파일 <파일명>을 찾을 수 없습니다

QDoc이 명령에 지정된 이름의 포함 파일을 찾지 못했습니다. QDoc은 검색 경로에 지정된 각 디렉터리를 검색합니다. 해당 디렉터리 중 어느 곳에도 이 이름의 파일이 없거나, 검색 결과로 발견된 파일이 읽기 권한이 없는 경우, QDoc은 이 경고를 표시합니다. 검색 경로와 <파일명>의 조합이 올바르게 입력되었는지, 그리고 해당 파일에 대한 읽기 권한이 있는지 확인하십시오.

<file>에서 <tag>를 찾을 수 없음

이는 QDoc이 <file>에서 식별자 <id>를 찾을 수 없음을 의미합니다. \include <file> 또는 {snippet-command}{\snippet} <file>에서 식별자 <id>를 찾을 수 없다는 의미입니다.

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

예:

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

문서화 프로젝트 QMake가 지정된 인덱스 디렉터리 중 어느 곳에서도 activeqt.index를 찾을 수 없습니다. 이 경우, 지정된 인덱스 디렉터리는 qmake.qdocconf에 명시되어 있습니다.

<command> 명령을 중첩할 수 없음

이 경고는 서식 지정 명령어(bold, italic, index, link, span, subscript, superscript, teletype, uicontrol, underline)와 관련이 있습니다. 서식 지정 명령어는 해당 명령어가 적용되는 텍스트 내부에서는 사용할 수 없습니다. 예시:

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

QDoc에서 “'\table'를 '\list'에서 사용할 수 없습니다”라는 경고가 발생합니다.

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

<filename>에 대한 검색 경로는 .qdocconf 파일의 다음 변수들에 의해 정의됩니다: sources, sourcedirs, exampledirs.

QDoc이 명령어에 지정된 파일(예: \quotefromfile, \snippet, \include)에서 지정한 파일의 내용을 가져오라는 지시를 받았으나, 해당 파일을 찾지 못했습니다. QDoc은 검색 경로에 지정된 각 디렉터리를 검색합니다. 해당 디렉터리 중 어느 곳에도 이 이름의 파일이 없거나, 파일이 발견되었으나 읽기 권한이 없는 경우, QDoc은 이 경고를 표시합니다. 검색 경로와 <filename>의 조합이 올바르게 표기되었는지, 그리고 해당 파일에 대한 읽기 권한이 있는지 확인하십시오.

이 문서를 어떤 항목에도 연결할 수 없습니다

QDoc이 토픽 명령어가 없는 /*! ... */ 주석을 발견했으나, 주석 바로 뒤에 나오는 선언이나 정의를 문서화된 엔티티와 연관 지을 수 없었습니다. 이 문제는 주석 뒤에 선언이나 정의가 없거나, QDoc이 평가하지 않는 전처리기 조건문 뒤에 선언이 있는 경우와 같이 QDoc이 해당 엔티티를 인식할 수 없는 경우에 발생할 수 있습니다.

<class>가 자기 자신을 상속하려고 합니다

<inherit> \inherits 명령은 QML 유형이 다른 QML 유형을 상속한다는 사실을 문서화하는 데 사용됩니다. 이 경고는 해당 다른 QML 유형이 문서화된 QML 유형과 동일한 경우 발생합니다.

예:

\qmltype Foo
\inherits Foo

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

예시:

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

이 경우, 이 경고는 \snippet 명령어가 스니펫의 끝을 표시하는 두 번째 레이블 "//! [2]"를 찾지 못했음을 의미합니다. 또한 이 스니펫 파일에서 해당 스니펫 태그가 전혀 발견되지 않았음을 의미할 수도 있습니다.

또 다른 예시:

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

\skipto + <pattern>은 해당 패턴이 포함된 다음 줄로 커서를 이동시킵니다. \skipto 가 해당 패턴을 찾지 못하면 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은 경로의 마지막 요소가 <group>.<property>인 속성 그룹을 문서화하기 위해 단일 문서 주석 내에서 여러 개의 qmlproperty 또는 qmlattachedproperty 토픽 명령을 허용합니다. 그 외의 다른 토픽 명령을 사용하면 이 경고가 발생합니다.

<name> 유형에 대한 QML 임포트 문을 해결할 수 없습니다

QML 타입을 문서화할 때 \inqmlmodule 명령을 생략한 경우 이 경고를 표시합니다. 예시:

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

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

올바른 예:

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

순환형 상속: <type>

순환 상속은 QML 유형이 원래 유형에서 상속받은 기본 유형을 다시 상속할 때 발생합니다. 이는 서로 상속 관계에 있는 두 유형 사이에서 발생할 수도 있고, 그 사이에 중간 유형이 존재할 수도 있습니다.

이 경고는 상속 계층 구조에서 순환이 감지된 위치를 나타냅니다. 해당 유형에 대한 \inherits 명령어를 확인하고, 이전에 접했던 타입으로부터 상속받는 기본 타입이 발견될 때까지 기본 타입의 계보를 따라가야 합니다. 그런 다음, 식별된 타입 중 하나에 대한 잘못된 \inherits 명령어를 수정하여 순환 구조를 끊어야 합니다.

의존 모듈이 지정되었으나 인덱스 디렉터리가 설정되지 않았습니다.

QDoc은 명령줄에서 하나 이상의 –indexdir 인수를 기대합니다. 이 인수가 없으면 QDoc은 'depends' 구성 변수로 정의된 종속성의 인덱스 파일을 찾을 수 없습니다.

<project>에 대한 문서 구성에서 도움말 프로젝트(qhp)가 정의되어 있지 않습니다.

유효한 Qt Help 구성이 필요하지만 프로젝트의 .qdocconf 파일에 제공되지 않았습니다.

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

중복된 대상 이름 <target>

다음 중 하나를 사용하여 동일한 매개변수를 가진 두 개의 타깃을 정의한 경우 이 경고가 표시됩니다. \target 또는 \keyword 명령어를 사용하여 동일한 매개변수를 가진 두 개의 타깃을 정의할 경우 이 경고가 표시됩니다. 이 명령어의 매개변수로 지정된 타깃 이름은 고유해야 합니다. 경고 뒤에는 "이전 발생 위치는 다음과 같습니다: [위치]"라는 메시지가 표시되며, 여기서 위치는 파일 이름과 줄 번호를 포함합니다.

<파일>의 빈 qdoc 스니펫 <태그>

<file>에서 <tag> 스니펫이 발견되었으나 \snippet <파일>에서 스니펫 <태그>가 발견되었으나, 내용이 비어 있습니다.

\fn 의 <시그니처>를 파싱하는 중 함수를 찾지 못했습니다

Clang이 \fn 명령어 뒤에 나오는 함수 시그니처를 파싱할 때, 헤더 파일의 선언과 대조하여 확인합니다. Clang이 불일치를 발견하면 이 경고 메시지를 표시합니다.

시그니처는 완전히 한정되어야 합니다. 일반적인 문제로는 템플릿 인자, 반환 유형 또는 const와 같은 한정자가 누락되었거나 잘못된 경우가 있습니다.

qhp.<project>.subprojects.<subproject>.indexTitle을(를) 찾을 수 없음

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

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

자세한 내용은 도움말 프로젝트 파일 만들기를 참조하십시오.

<파일>을 쓰기 모드로 열지 못했습니다

이 경고는 쓰기 목적으로 파일을 열 수 없음을 분명히 나타내며, 이는 경로가 잘못되었거나 특정 디렉터리에 대한 쓰기 권한이 부족하기 때문일 가능성이 높습니다.

테이블 항목 외부에서 \target 명령이 발견되었습니다

QDoc이 \table... \endtable 블록 내에서 \li 명령이 앞에 붙지 않은 \target 명령을 발견하면 이 경고를 표시합니다. 경고 뒤에는 “이 경고를 해결하려면 \target 를 \li 안으로 이동하십시오.”라는 텍스트가 이어집니다.

\generatelist <group>이 비어 있습니다

다음은 \generatelist:

• \generatelist 주석이 달린 예제
• \generatelist 주석이 달린 출처
• \generatelist 클래스 <접두사>
• \generatelist 모듈별 클래스 <모듈 이름>
• \generatelist 모듈별 QML 유형 <모듈 이름>
• \generatelist 함수 색인
• \generatelist 법적 고지
• \generatelist 개요
• \generatelist 저작권 표시
• \generatelist 관련 항목

\generatelist <group> 를 지정했는데 그룹에 항목이 없거나, \generatelist <group> <pattern> 를 지정했는데 그룹 내의 항목 중 패턴과 일치하는 항목이 없는 경우 QDoc은 이 경고를 표시합니다.

\generatelist <group> 해당 그룹이 없습니다

다음과 같은 경우 이 경고가 표시됩니다. \generatelist 인수가 존재하지 않는 그룹인 경우 이 경고가 표시됩니다.

예:

\generatelist draganddrop

이 문장은 draganddrop 그룹에 속한 클래스 또는 QML 유형의 목록을 생성합니다. 클래스나 QML 유형은 \l {ingroup-command}{\ingroup} draganddrop 명령을 통해 \class 또는 \qmltype 주석에 `xml-ph-0000@deepl.internal` 명령어를 사용하여 `draganddrop` 그룹에 클래스나 QML 유형이 추가됩니다.

이 ' \ingroup draganddrop ' 문이 포함된 엔티티가 없으면 QDoc에서 이 경고 메시지를 표시합니다.

\inmodule 명령어가 없습니다

QDoc 주석이 \inmodule 명령을 사용하여 클래스, 네임스페이스 또는 헤더 파일을 모듈과 연결하지 않은 경우 QDoc은 이 경고를 표시합니다.

QDoc 주석이 다른 엔티티(일반적으로 네임스페이스나 클래스)의 구성원이 아닌 엔티티를 설명하는 경우, 다음 중 하나를 사용해야 합니다. \relates 또는 \inmodule 를 사용하여 더 넓은 맥락과 연관시켜야 합니다. 그렇지 않을 경우 이 경고가 발생합니다.

\reimp 는 유효하지 않습니다. <command>에 대한 문서화된 가상 함수가 없습니다.

QDoc은 이 함수가 재구현하는 함수에 대한 링크를 생성하려고 시도했으나, 해당 함수가 문서화되지 않았기 때문에 링크 대상을 찾을 수 없었습니다. 또한, 이 이름과 시그니처를 가진 가상 메서드를 가진 기본 클래스가 없는 경우에도 이 문제가 발생할 수 있으며, 이는 이름 변경, 시그니처 변경 또는 기본 클래스에서 더 이상 가상 메서드로 선언하지 않은 경우로 인해 발생할 수 있습니다.

잘못된 QML 속성 유형

QML 속성을 선언하는 데 사용된 유형이 유효한 QML 값 유형이나 QML 객체 유형이 아니거나, C++ 또는 Qt 유형입니다.

이 경고는 일반적으로 개발자가 list<string> 대신 QStringList 과 같이 QML 유형을 구현하는 데 사용되는 기본 Qt 유형을 참조할 때 발생합니다.

유효하지 않은 정규식 <regex>

일부 QDoc 명령어는 정규 표현식을 매개변수로 받습니다. QDoc은 이러한 매개변수로 지정된 텍스트가 유효한 정규 표현식이 아닐 때 이 경고를 표시하며, 이는 주로 정규 표현식에서 특수한 의미를 갖는 문자가 포함되어 있어 이스케이프 처리되어야 했음에도 처리되지 않았기 때문입니다.

예시:

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

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

잘못된 정규 표현식:

\printuntil /^})$/

유효한 정규 표현식:

\printuntil /^\}\)$/

\printuntil 명령어는 오른쪽 중괄호와 그 뒤에 오는 오른쪽 괄호로만 구성된 줄을 만나기 전까지 출력합니다. 이 경우, 중괄호와 괄호는 정규 표현식에서 특별한 의미를 가지므로 이스케이프 처리해야 합니다.

매크로는 형식별 정의와 qdoc 구문 정의를 동시에 가질 수 없습니다

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

이 경고를 유발하는 구성의 예:

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

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

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

예시:

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

그러나 매크로 확장에 포맷에 구애받지 않는 매크로가 필요한 경우도 있습니다. 예를 들어, 섹션 제목에 매크로를 사용할 수는 있지만, 이 매크로들은 기본 정의가 반드시 있어야 합니다.

매크로 <macro>가 인수가 너무 적게 전달되어 호출되었습니다(예상: <many>, 실제: <few>)

지정된 매크로에는 전달된 것보다 더 많은 매개변수가 필요합니다. 자세한 내용은 구성 파일의 매크로 정의를 참조하십시오.

다음에서 쉼표가 누락되었습니다 \sa

명령어에 나열된 \sa 명령어에 나열된 제목들은 쉼표로 구분되어야 합니다.

뒤에 형식 이름이 누락되었습니다 \raw

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

이미지 누락: <imagefile>

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

<inner> 앞에 <outer>가 누락되었습니다

몇 가지 예시:

• 이 \li 명령어는 \list 또는 \row 의 \table.
• 이 \row 및 \header 명령어는 \table.

<name>에 대한 속성 유형이 누락되었습니다.

다음의 선언에서 \qmlproperty 의 선언에서 속성 유형이 누락되었습니다.

\qmlproperty 명령어는 그 뒤에 속성 유형이 오고, 그 다음에 속성의 완전한 정규화된 이름(즉, 해당 속성이 속한 클래스 이름 뒤에 ::-로 연결된 이름)이 따라와야 합니다.

잘못된 예:

\qmlproperty MyWidget::count

올바른 예:

\qmlproperty int MyWidget::count

의존성 <indexfile>에 대해 여러 개의 인덱스 파일이 발견되었습니다:<depend>

의존성 <depend>에 대한 인덱스 파일로 <indexfile>을 사용합니다.

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

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

<function>에 대한 여러 개의 기본 오버로드 정의

QDoc은 동일한 이름을 가진 여러 함수가 \overload primary 로 표시되어 있을 때 이 경고를 표시합니다. 오버로드 그룹 내에서는 단 하나의 함수만 주 오버로드로 지정되어야 합니다.

이 경고에는 경쟁 관계에 있는 모든 주 오버로드를 식별하는 데 도움이 되도록 함수 시그니처와 해당 소스 위치가 포함됩니다. QDoc은 주 오버로드로 표시된 함수들 간에 사전순 비교(함수 시그니처의 알파벳순 정렬)를 통해 실제 주 오버로드를 결정합니다.

이 경고를 해결하려면, 오버로드 그룹 내의 모든 ` \overload primary ` 명령어 중에서 하나를 제외한 나머지에서 ` primary ` 인수를 제거하십시오.

이 경고를 유발하는 예시:

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload primary
    Does something with a parameter.
*/
void doSomething(int value);

올바른 방법 - 주 오버로드는 하나만 지정:

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload doSomething()
    Does something with a parameter.
*/
void doSomething(int value);

<name>이 두 번 이상 문서화되었습니다

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

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

<name>에 대한 설명은 있지만, 네임스페이스 <namespace>는 어떤 모듈에서도 설명되어 있지 않습니다

<name> 에 대한 문서는 발견되었으나, <name> 이 문서화되지 않은 네임스페이스 아래에서 선언되었거나 QDoc이 해당 네임스페이스의 문서를 찾을 수 없는 경우입니다.

이 문제는 <namespace>에 대한 문서를 작성하거나, 다른 모듈에 이미 문서가 있는 경우 이 모듈이 해당 모듈에 대한 종속성을 갖도록 설정하여 해결할 수 있습니다.

'depends ' 및 'indexes' 항목도 참조하십시오.

네임스페이스 <name>이 두 번 이상 문서화되었습니다.

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

\nativetype 는 다음에서만 허용됩니다. \qmltype

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

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

예:

Warning "No documentation for QNativeInterface."

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

전역 범위 내의 함수 <name>에 대한 문서가 생성되지 않았습니다

QDoc은 함수 <name> 에 대한 문서를 해당 선언과 매칭할 수 있었지만, 함수가 전역 네임스페이스에 선언되어 있어 출력이 생성되지 않았습니다.

다음 \relates 명령어를 사용하여 함수를 문서화된 유형, 네임스페이스 또는 헤더 파일과 연결하십시오. 그러면 해당 함수는 연결된 참조 페이지에 관련 비멤버로 나열됩니다.

<parent>에 대한 문서가 없으므로 <entity>에 대한 출력이 생성되지 않았습니다

QDoc은 클래스 멤버와 같은 API 엔티티에 대한 문서 주석을 구문 분석할 때 이 경고를 표시하지만, 관련 부모(클래스)에 대한 문서가 없어 출력을 생성할 수 없습니다. 부모에 대한 문서가 있는지 확인하고, 문서 주석이 포함된 소스 파일을 구문 분석하도록 QDoc이 구성되어 있는지 확인하십시오.

문서화된 멤버가 문서화 대상이 아닌 클래스에 속하는 경우, 해당 클래스를 \internal 로 표시하거나 \dontdocument 명령을 사용하십시오.

<class>에 <name>이라는 열거형 항목이 없습니다.

예:

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

QDoc은 \value 지시문을 발견하면 \enum 주석 내에서 문서화된 열거형 타입을 선언한 헤더 파일에서 찾을 수 없는 값을 지정한 경우, QDoc은 이 경고를 표시합니다.

해당 매개변수가 없습니다

QDoc은 \a 명령 뒤에 지정된 매개변수 이름이, 문서화 대상인 함수나 메서드의 헤더 파일 선언에 명시된 매개변수 중 어느 것과도 일치하지 않을 때 이 경고를 표시합니다.

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

QDoc은 \qmlproperty, \qmlmethod, 또는 \qmlsignal 명령어 인수가 QML 모듈 식별자를 사용하지만, 관련 \qmltype 해당 모듈에 속하지 않을 때 이 경고를 표시합니다.

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

기존 문서를 덮어씁니다

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

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

QDoc은 동일한 QML 속성을 설명하는 두 개의 QDoc 주석을 발견할 때 이 경고를 표시합니다. 해당 주석은 속성 정의 바로 앞에 위치하거나 \qmlproperty 명령을 사용하여 동일한 QML 속성을 설명하는 두 개의 QDoc 주석을 발견했을 때 이 경고를 사용합니다.

QML 유형 <TypeName>이 네이티브 유형으로 <ClassName>을 사용하여 문서화되었습니다. <ClassName>을 <OtherClass>로 대체

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

QtDeclarative가 설치되지 않았습니다. QML을 구문 분석할 수 없습니다.

QDoc이 QML 구문 분석 기능을 지원하지 않는 상태로 컴파일된 경우 이 경고가 표시됩니다. 사용자 정의 QDoc 빌드를 사용하지 않는 한 이러한 현상은 발생하지 않아야 합니다.

<name>에 대한 \sa 명령어에서 자체 참조가 중복되었습니다

특정 문서의 \sa 명령에 정의된 참조에 자체에 대한 링크가 포함되어 있습니다.

이 문제는 서로 참조하는 관련 속성이나 메서드들이 모여 있고, 다음 예시와 같이 \sa 명령이 이들 간에 복사된 경우에 주로 발생합니다:

\fn void Items::append(const Item &)
...
\sa append(), count(), insert(), remove()

이러한 자기 참조 링크를 다른 관련 속성이나 메서드로 연결된 링크로 대체하는 것이 유용합니다.

또는 다음 예시와 같이 링크가 QDoc이 해결할 수 있을 만큼 구체적이지 않을 수도 있습니다:

\fn void MyPicture::setSize(int)
...
\sa setSize()

이 경우, double 인자를 받는 오버로드를 참조하려는 의도였을 수 있습니다:

\fn void MyPicture::setSize(int)
...
\sa setSize(double)

내용이 너무 깁니다

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.]

이 페이지 제목이 두 개 이상의 파일에 존재합니다

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

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

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

이 qdoc 주석에는 topic 명령어(예: \module, \page)가 포함되어 있지 않습니다.

QDoc 주석에 topic 명령어가 포함되어 있지 않으면, QDoc은 해당 주석이 무엇을 설명하는지 알 수 없으므로 이 경고를 표시합니다. “이 문서를 어떤 것과도 연결할 수 없습니다”와 매우 유사하지만, C++ 또는 QML 파일에 포함되지 않은 주석에 한정됩니다.

<topic>은 다른 topic 명령어와 혼합할 수 없습니다

QDoc은 특정 사용 사례에 대해 단일 문서 주석 내에 여러 개의 topic 명령어를 허용합니다. 서로 다른 범주의 topic 명령어를 여러 개 사용하면 이 경고가 출력되며, 해당 topic은 아무런 출력도 생성하지 않습니다.

타입이 자체 기본 타입입니다: <type>

QML 타입이 자체 기본 타입으로 잘못 정의되었습니다. 아마도 \inherits 명령어를 사용했을 가능성이 있습니다.

QML 스니펫을 구문 분석할 수 없음: <code> (줄 <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... \endcode 로 대체하여 이 경고를 억제해도 무방합니다.

<text> 내 괄호 불일치

대응되는 ')'가 없는 '('가 있거나, 그 반대의 경우를 나타냅니다.

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

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

문서화되지 않은 매개변수

QDoc은 함수나 메서드의 문서에서 모든 매개변수를 설명할 것을 요구합니다. QDoc은 헤더 파일에서 함수나 메서드가 선언된 위치에 명시된 각 매개변수 이름이 \a 명령 뒤에 나타나야 한다고 규정합니다.

이 요구 사항은 함수 오버로드 문서화의 경우, 해당 오버로드가 \overload 명령으로 표시되어 있고, 동일한 이름을 가진 완전히 문서화된 함수가 존재하는 경우, 이 요구 사항은 적용되지 않습니다.

문서화되지 않은 속성 '<이름>'

이 경고는 C++ 클래스에 설명이 누락된 Q_PROPERTY 선언이 있음을 나타냅니다. 속성은 클래스의 공개 API의 일부이며, 그 목적, 유효한 값 및 동작을 설명하기 위해 \property 명령을 사용하여 설명해야 합니다.

<type> 또는 그 멤버가 참조하는 문서화되지 않은 QML <module>

QDoc은 다음 명령어에 전달된 식별자를 기반으로 QML 모듈을 찾을 수 없는 경우 이 경고를 표시합니다. \inqmlmodule 또는 \qmlproperty 명령에 전달된 식별자를 기반으로 QML 모듈을 찾을 수 없는 경우 이 경고를 표시합니다.

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

문서화되지 않은 반환 값

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

예상치 못한 <end_command>

예를 들어, 다음과 같이 \endlist 앞에 \list가 없는 경우 발생합니다. 이는 쌍을 이루는 모든 명령(예: startFoo/endFoo)에 적용됩니다.

예상치 못한 \snippet

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

QML 유형 <type>에 대한 알 수 없는 기본 유형 <name>

QML 유형의 기본 유형으로 선언된 유형 이름을 찾을 수 없거나, 해당 유형이 \inherits 명령어로 선언되지 않았습니다.

알 수 없는 명령어 <name>

QDoc 주석에서 백슬래시 뒤에 QDoc 내장 명령어가 아니며 사용자 정의 명령어 매크로로 정의되지 않은 토큰이 사용된 경우, QDoc은 이 경고를 표시합니다. 명령어 이름의 철자를 확인하고, 사용자 정의 명령어인 경우 QDoc 구성에 해당 명령어를 정의하는 내용이 포함되어 있는지 확인하십시오.

또한 QDoc 주석 내에서 코드가 따옴표로 묶여 있는 경우에도 이 경고가 발생할 수 있습니다. 예를 들어, 작성자가 백슬래시를 이스케이프 처리하지 않은 채 C 문자열 종료 문자( '\0' )나 '\n' 와 같은 다른 C 문자열 이스케이프 시퀀스를 참조했을 수 있습니다. 문서에 리터럴 백슬래시를 포함시키려면 백슬래시를 \ 로 이스케이프하거나, 코드 조각을 \c{...} 로 묶어 백슬래시가 QDoc 명령을 시작하는 것으로 해석되지 않도록 하십시오.

알 수 없는 매크로

QDoc은 백슬래시( \) 뒤에 내장 명령어나 사용자 정의 매크로 이름으로 인식되지 않는 토큰이 이어지는 경우 이 경고를 표시합니다. 문자 이스케이프 시퀀스가 포함된 코드를 인용할 때는, 이스케이프 시퀀스에 대한 이 경고가 발생하지 않도록 코드를 \c{...}로 감싸야 합니다.

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

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

예:

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

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

알 수 없는 목록 스타일 <name>

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

알 수 없는 마크업 언어

이 경고는 QDoc이 인식하지 못하는 프로그래밍 언어가 \code 명령에 지정되었을 때 발생합니다. 예를 들어, 다음 QML 코드 블록에는 유효하지 않은 "QL" 언어가 지정되었습니다:

\code [QL]
Item {
    id: my_item
}
\endcode