QDoc 경고 문제 해결

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

<대상>에 연결할 수 없음

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

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

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

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

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

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

인용할 코드 조각 파일을 찾을 수 없음

QDoc은 다음 이름을 가진 파일을 찾을 수 없는 경우 이 경고를 발행합니다. \snippet 또는 \quotefromfile 명령 뒤에 이름이 지정된 파일을 찾을 수 없는 경우 이 경고가 표시됩니다.

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

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

예기치 않은 \snippet

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

<유형> 또는 그 멤버가 참조하는 문서화되지 않은 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 명령으로 오버로드가 표시되고 같은 이름의 문서화된 함수가 존재하는 경우에는 이 요구 사항이 적용되지 않습니다.

그러한 매개 변수 없음

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

알 수 없는 매크로

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

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

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

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

<부모>가 문서화되지 않았으므로 <엔티티>에 대한 출력이 생성되지 않음

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

문서화된 멤버가 문서화할 수 없는 클래스에 속하는 경우 해당 클래스를 \internal 로 표시하거나 \dontdocument 명령을 사용합니다.

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

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

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

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

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

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

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

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

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

<topic>은 다른 토픽 명령과 혼합할 수 없습니다.

QDoc에서는 특정 사용 사례에 대해 하나의 문서 댓글에 여러 개의 토픽 명령을 허용합니다. 서로 다른 카테고리의 여러 토픽 명령을 사용하면 이 경고가 인쇄되며 토픽은 출력을 생성하지 않습니다.

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

이 경고는 문서 집합에 동일한 인수가 포함된 두 개의 댓글이 포함되어 있음을 의미합니다. \namespace 인수가 같은 <이름> 명령이 포함된 문서 집합이 두 번 이상 문서화되었음을 의미합니다.

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

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

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

의존성 및 인덱스도 참조하세요.

\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

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

이 경고는 C++ 클래스에 문서가 없는 Q_PROPERTY 선언이 있음을 나타냅니다. 프로퍼티는 클래스의 공용 API의 일부이며 \property 명령을 사용하여 목적, 유효한 값 및 동작을 설명하는 문서가 필요합니다.

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

QDoc은 동일한 QML 속성을 문서화하는 두 개의 QDoc 주석을 정의 바로 앞에 표시하거나 \qmlproperty 명령을 사용합니다.

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>에 대한 문서화된 가상 함수가 없습니다.

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

<함수>에 대한 여러 기본 과부하 정의

같은 이름을 가진 여러 함수가 \overload primary 로 표시된 경우 QDoc에서 이 경고를 발행합니다. 과부하 그룹에서 하나의 함수만 기본 과부하로 지정해야 합니다.

경고에는 모든 경쟁하는 기본 과부하를 식별하는 데 도움이 되는 함수 서명 및 소스 위치가 포함됩니다. 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);

<class>가 스스로 상속을 시도합니다.

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

예제:

\qmltype Foo
\inherits Foo

\nativetype 는 \qmltype

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

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

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

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

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

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

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

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

뒤에 형식 이름이 누락됨 \raw

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

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

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

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

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이 <파일>에서 식별자 <id>를 찾을 수 없음을 의미합니다. \include <파일> 또는 {스니펫-명령}{\snippet} <파일>에서 식별자를 찾을 수 없습니다.

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

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

<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 또는 a \row 의 \table.
• 그리고 \row 과 \header 명령은 a 내에서만 사용할 수 있습니다. \table.

예기치 않은 <END_COMMAND>

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

쉼표가 누락되었습니다. \sa

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

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

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.

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

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

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

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

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

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

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

\generatelist <그룹>이 비어 있습니다.

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

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist 클래스 <접두사>
• \generatelist 클래스별 모듈 <모듈 이름>
• \generatelist qmltypesbymodule <모듈 이름>
• \generatelist functionindex
• \generatelist legalese
• \generatelist overviews
• \generatelist 어트리뷰션
• \generatelist 관련

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

\generatelist <그룹> 해당 그룹 없음

인수가 \generatelist 인수가 존재하지 않는 그룹인 경우 이 경고가 발생합니다.

예제:

\generatelist draganddrop

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

이 \ingroup draganddrop 문이 있는 엔티티가 없는 경우 QDoc은 이 경고 메시지를 표시합니다.

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

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

<대상>에 연결할 수 없음

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

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

<이름> 유형에 대한 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

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은 목록 스타일을 수정하는 단일 숫자 또는 문자를 선택적 인수로 사용할 수 있습니다. 자세한 내용은 {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

이러한 경우 이 경고를 표시하지 않으려면 \qml... \endqml 명령을 \code... \endcode 로 바꾸면 됩니다.

<파일 이름> 파일 끝에서 <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 + <패턴>은 커서를 해당 패턴이 포함된 다음 줄로 이동합니다. \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> 함수에 대한 설명서를 선언과 일치시킬 수 있었지만 함수가 전역 네임스페이스에 선언되어 있기 때문에 출력이 생성되지 않았습니다.

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

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

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

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

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

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

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

잘못된 QML 속성 유형

QML 프로퍼티를 선언하는 데 사용된 유형이 유효한 QML 값 유형 또는 QML 객체 유형이 아니거나 C++ 또는 Qt 유형인 경우입니다.

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

유형이 자체 기본 유형인 경우: <type>

QML 유형이 자체 기본 유형으로 잘못 정의되어 있을 수 있습니다. \inherits 명령을 사용했을 수 있습니다.

순환 유형 상속: <유형>

순환 또는 순환 상속은 QML 유형이 원래 유형에서 상속되는 기본 유형에서 상속될 때 발생합니다. 이는 상호 상속하는 두 유형 사이에서 발생하거나 두 유형 사이에 중간 유형이 있을 수 있습니다.

이 경고는 상속 계층 구조에서 주기가 감지된 위치를 나타냅니다. 유형에 대한 \inherits 명령에서 해당 유형을 검사하고 이전에 접했던 유형에서 상속되는 유형을 찾을 때까지 기본 유형의 흔적을 따라가야 합니다. 그런 다음 식별된 유형 중 하나에 대해 잘못된 \inherits 명령을 수정하여 사이클을 끊어야 합니다.

<이름>에 대한 \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)

QML 유형 <유형>에 대한 알 수 없는 기본 <이름>입니다.

QML 유형의 기본 유형으로 선언된 유형 이름이 발견되지 않았거나 \inherits 명령으로 선언되지 않았습니다.

인식할 수 없는 마크업 언어

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

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