QDocの警告のトラブルシューティング

QDocは、ドキュメントセットを生成する際に警告を表示する場合があります。このセクションでは、これらの警告の意味と解決方法について説明します。なお、本ドキュメントではClangによって生成される警告については扱いません。

グループ内のすべてのプロパティは、同じ型に属している必要があります: <name>

QML プロパティグループをドキュメント化する際、コメントブロックにリストされているすべてのプロパティは、同じ QML 型に属している必要があります。

このプロジェクト用に <file> はすでに生成されています

プロジェクトのドキュメントを生成する際、QDocは生成済みのファイル名を追跡します。QDocは、書き込み用にファイルを開こうとした際、そのファイルが現在の実行中に以前に生成されたことがわかっている場合、警告を出力します。これは、 \page コマンドが \group を使用している場合などに発生します。

環境変数QDOC_ALL_OVERWRITES_ARE_WARNINGS を設定すると、このようなイベントすべてについて無条件に警告が表示されます。これは、問題のある定義を特定する際に役立つ場合があります。

\brief 文がピリオドで終わっていない場合

\brief コマンドの引数は、ドキュメント化されるトピックを要約した文章であるため、ピリオドで終わる必要があります。また、簡潔であるべきです。

<target> へのリンクができません

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.

ドキュメントコメントでは列挙型（enum）の説明とされているが、QDocはヘッダーファイル内でその列挙型の定義を見つけられなかった。

この原因は、以下の可能性もあります：

• <name> または <command> の入力ミス
• 名前空間またはクラスのプレフィックスが欠落している
• <name> が別の名前空間またはクラスに移動した

例 <name> のプロジェクトファイルが見つかりません

例のソースディレクトリ内には、QDocはCMakeLists.txt という名前のプロジェクトファイル、あるいは拡張子が.pro 、.qmlproject 、または.pyproject で、ベース名が例のディレクトリ名と一致するファイルが存在することを期待しています。例えば、examples/mymodule/helloworld/helloworld.pro などです。

引用元のスニペットファイルが見つかりません

QDocは、 \snippet または \quotefromfile コマンドにちなんで名付けられたファイルが見つからない場合、この警告を表示します。

この問題を修正するための有用な手順は以下の通りです：

• スニペットファイル名が正しいか確認してください。QDocは、検索パスに指定された各ディレクトリにスニペットファイル名を付加し、検索対象となる候補ファイルのパス名を生成します。これらの候補ファイルがすべて存在しない場合、このエラーが発生します。
• *.qdocconf ファイル内のexampledirs 設定変数で指定されているスニペットの検索パスを確認してください。このパスにエントリを追加するか、既存のエントリを修正する必要があるかもしれません。
• スニペットファイルが存在するか、あるいは移動・名前変更・削除されていないかを確認してください。これは、QDocが引用しようとするソースコードに変更があった場合に発生する可能性があります。

qdoc インクルードファイル <filename> が見つかりません

QDoc は、コマンドで指定された名前のインクルードファイルを見つけられませんでした。QDoc は、検索パスに指定された各ディレクトリを検索します。それらのディレクトリのいずれにもこの名前のファイルがない場合、または検索で見つかったファイルが読み取り不可である場合、QDoc はこの警告を出力します。 検索パスと <filename> の組み合わせのスペルが正しいこと、およびそのファイルに対する読み取り権限があることを確認してください。

<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> コマンドをネストできません

この警告は、太字、斜体、索引、リンク、スパン、下付き文字、上付き文字、テレタイプ、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

その結果、QDocから「'\table'を'\list'内で使用できません」という警告が表示されます。

引用元のファイルを開けません: <filename>

<filename> の検索パスは、.qdocconf ファイル内の以下の変数によって定義されています：sources 、sourcedirs 、およびexampledirs 。

QDoc は、コマンドで指定されたファイル（例： \quotefromfile、 \snippet, \include）で指定されたファイルからコンテンツを取得するよう指示するファイルが見つかりませんでした。QDoc は、検索パスに指定された各ディレクトリを検索します。これらのディレクトリのいずれにもこの名前のファイルが存在しない場合、またはファイルは見つかったものの読み取り権限がない場合、QDoc はこの警告を表示します。 検索パスと <filename> の組み合わせのスペルが正しいこと、およびそのファイルに対する読み取り権限があることを確認してください。

このドキュメントを何にも紐付けできません

QDoc は、トピックコマンドのない /*! ... */ コメントを検出し、そのコメントの直後に続く宣言または定義を、ドキュメント化されたエンティティに関連付けることができませんでした。 これは、コメントの直後に宣言や定義がない場合、または宣言が QDoc が評価しないプリプロセッサ条件式の後ろにあるなど、QDoc からそのエンティティが見えない場合に発生することがあります。

<class> が自分自身を継承しようとしています

<class> が自身を継承しようとしています。 \inherits コマンドは、ある QML 型が別の QML 型を継承していることをドキュメント化するために使用されます。この警告は、その別の QML 型が、ドキュメント化されている QML 型と同じである場合に表示されます。

例:

\qmltype Foo
\inherits Foo

コマンド <command> がファイル <filename> の末尾で失敗しました

例：

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

この場合、この警告は、 \snippet コマンドが、スニペットの終わりを示す2つ目のラベル「//! [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 型が、その型自体を継承している基底型から継承する場合に発生します。これは、相互に継承し合う 2 つの型の間で発生することもあれば、その間に中間型が存在する場合もあります。

この警告は、継承階層内でループが検出された箇所を示しています。該当するタイプの \inherits コマンドを確認し、以前に遭遇した型から継承している基底型が見つかるまで、基底型の連鎖をたどってください。その後、特定された型のうちいずれかについて、誤った \inherits コマンドを修正して、ループを解消してください。

依存モジュールが指定されていますが、インデックスディレクトリが設定されていません。

QDoc は、コマンドライン上で 1 つ以上の –indexdir 引数が指定されることを期待しています。これらが指定されていない場合、QDoc は 'depends' 設定変数で定義された依存関係のインデックスファイルを検出できません。

<project> のドキュメント設定でヘルププロジェクト (qhp) が定義されていません

有効な Qt Help 設定が期待されていますが、プロジェクトの .qdocconf ファイルには指定されていません。

「ヘルププロジェクトファイルの作成」および「qhp」も参照してください。

ターゲット名 <target> が重複しています

この警告は、 \target または \keyword コマンドのいずれかを使用して、同じパラメータを持つ2つのターゲットを定義した場合に、この警告が表示されます。これらのコマンドのパラメータとして指定されるターゲット名は一意である必要があります。警告の後に「前の出現箇所はここです：[location]」と表示されます。ここで、location にはファイル名と行番号が含まれます。

<file> 内の空の qdoc スニペット <tag>

<file> 内のスニペット <tag> が検出されましたが、 \snippet <file> 内でスニペット <tag> が検出されましたが、内容は空です。

\fn <signature> の解析中に関数が見つかりませんでした

Clang が \fn コマンドに続く関数シグネチャを解析する際、ヘッダーファイル内の宣言と照合します。Clang が不一致を発見した場合、この警告メッセージが表示されます。

シグネチャは完全修飾されている必要があります。典型的な問題としては、テンプレート引数、戻り値の型、またはconst などの修飾子の欠落や誤りなどが挙げられます。

qhp.<project>.subprojects.<subproject>.indexTitle が見つかりませんでした

QDoc は、Qt Help プロジェクトの設定において <SUBPROJECT> のインデックスページとして指定されたページのタイトルを見つけられませんでした。

サブプロジェクトのインデックスタイトルは、現在のドキュメントプロジェクト内に存在する必要があります。依存関係として読み込まれた別のプロジェクトのページタイトルを使用した場合も、この警告が表示されます。

詳細については、「ヘルププロジェクトファイルの作成」を参照してください。

<file> を書き込み用に開くことができませんでした

この警告は、書き込み用にファイルを開くことができないことを明確に示しています。おそらく、パスが間違っているか、特定のディレクトリへの書き込み権限がないためです。

テーブル内のテーブル項目外で\target コマンドが見つかりました

QDocが、\table...\endtable ブロック内で、\li コマンドに続いていない\target コマンドを検出した場合、この警告が表示されます。警告の後に、「この警告を解決するには、\target を\li 内に移動してください」というテキストが表示されます。

\generatelist <group> が空です

以下に、 \generatelist:

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \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グループに追加されます。

この\ingroup draganddrop ステートメントを持つエンティティが存在しない場合、QDocはこの警告メッセージを表示します。

\inmodule コマンドがありません

QDoc コメントで、xml-ph-0000@deepl.internal コマンドを使用してクラス、名前空間、またはヘッダーファイルをモジュールに関連付けていない場合、QDoc はこの警告を出力します。 \inmodule コマンドでモジュールに関連付けていない場合、QDocはこの警告を出します。

QDoc コメントが、他のエンティティ（通常は名前空間やクラス）のメンバーではないエンティティについて記述している場合は、 \relates または \inmodule のいずれかを使用して、より広いコンテキストに関連付ける必要があります。そうしていない場合、この警告が表示されます。

無効な\reimp; <command> に対する文書化された仮想関数が見つかりません

QDocは、この関数が再実装している関数へのリンクを作成しようとしましたが、リンク先が見つかりませんでした。おそらく、その関数がドキュメント化されていないためです。また、この名前とシグネチャを持つ仮想メソッドを持つ基底クラスが存在しない場合にも発生する可能性があります。これは、名前の変更、シグネチャの変更、または基底クラスで仮想として宣言されなくなったことが原因である可能性があります。

無効な QML プロパティ型

QML プロパティの宣言に使用された型が、有効なQML 値型またはQML オブジェクト型ではなかったか、あるいは C++ または Qt の型でした。

この警告は通常、開発者が QML 型の実装に使用される基になる Qt 型を参照した場合に発生します。例えば、list<string> ではなくQStringList を使用している場合などです。

無効な正規表現 <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

<command> \sa コマンドでリストされたタイトルは、互いにコンマで区切られている必要があります。

の後にフォーマット名が欠けています\raw

[ \raw コマンドと対応する \endraw コマンドとそれに対応する\raw コマンドは、生のマークアップ言語コードのブロックを区切ります。 コマンドの後に、必ずフォーマット名を指定する必要があります。

画像が見つかりません: <imagefile>

画像への検索パスが間違っているか、画像ファイルが存在しません。

<inner>の前に<outer>が欠落しています

例：

• xml-ph-0000@deepl.internal \li コマンドは、 \list または \row の \table内でしか使用できません。
• この \row および \header コマンドは、 \table内でしか使用できません。

<name> のプロパティ型が指定されていません

の宣言において \qmlproperty の宣言にプロパティ型が欠けています。

\qmlproperty コマンドの後に、プロパティ型、続いてプロパティの完全修飾名（つまり、所属するクラスの名前の後に「:」で連結された名前）が続くことが求められます。

誤り:

\qmlproperty MyWidget::count

正しい例:

\qmlproperty int MyWidget::count

依存関係 <indexfile>:<depend> に対して複数のインデックスファイルが見つかりました

依存関係 <depend> のインデックスファイルとして <indexfile> を使用します

コマンドラインオプションとして複数の-indexdir パスがQDocに渡され、そのうちの複数に依存関係に一致する.index ファイルが含まれていました。QDocは、タイムスタンプが最も新しいものを自動的に選択します。

通常、この警告は、以前のドキュメント生成時に残されたビルド成果物があることを示しています。

<function> に対する複数のプライマリオーバーロード定義

QDocは、同じ名前の複数の関数が\overload primary でマークされている場合に、この警告を発行します。オーバーロードグループ内の関数のうち、1つだけをプライマリオーバーロードとして指定する必要があります。

この警告には、競合するすべてのプライマリオーバーロードを特定するのに役立つ、関数のシグネチャとそのソースの位置が含まれています。QDocは、プライマリとしてマークされた関数間で辞書順比較（関数シグネチャのアルファベット順）を行い、実際のプライマリオーバーロードを決定します。

この警告を解消するには、オーバーロードグループ内の\overload primary コマンドのうち、1つを除くすべてからprimary 引数を削除してください。

この警告が発生する例：

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

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

正しいアプローチ - プライマリを1つだけ指定:

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

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

<name> が複数回ドキュメント化されています

QDocは、同じ項目を記述する2つのコメントを検出した場合にこの警告を発します。以前に検出されたコメントの位置は、警告の詳細に表示されます。

たとえば、関数の定義の前にドキュメントコメントがあり、別の場所に\fn コメントが別途存在する場合に、この警告が表示されます。

<name> にはドキュメントがありますが、名前空間 <namespace> についてはどのモジュールにもドキュメントがありません

<name>のドキュメントは見つかりましたが、<name>は、ドキュメント化されていない名前空間の下で宣言されているか、QDoc がそのドキュメントを見つけられなかった名前空間の下で宣言されています。

この問題は、<namespace> にドキュメントを追加するか、あるいは別のモジュールですでにドキュメント化されている場合は、このモジュールがそれに依存していることを確認することで解決できます。

「depends」および「indexes」も参照してください。

名前空間 <name> が複数回ドキュメント化されています

この警告は、あるドキュメントセットに、 \namespace コマンドを含むコメントが2つ存在することを意味します。

\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 コマンドの後に指定されたパラメータ名が、ドキュメント化対象の関数またはメソッドのヘッダーファイル内の宣言で指定されているパラメータのいずれとも一致しない場合、QDocはこの警告を出力します。

QML <モジュール> にそのような <型> はありません

QDocは、 \qmlproperty、 \qmlmethod、または \qmlsignal コマンドの引数で QML モジュール識別子が使用されているにもかかわらず、関連する \qmltype が当該モジュールに属していない場合、この警告が出されます。

QML モジュール識別子が定義されている場合、それは\inqmlmodule 引数と一致している必要があります。ほとんどの場合、QDocはモジュール識別子なしでもQML型を特定できます。

既存のドキュメントを上書きしています

QDoc は、同じエンティティを記述していると思われる 2 つのコメントを検出した場合に、この警告を発行します。以前に検出されたコメントの位置は、警告の詳細に表示されます。

QML プロパティが複数回文書化されています: <識別子>

QDoc は、同じ QML プロパティを記述していると思われる 2 つの QDoc コメントを検出した場合、この警告を表示します。これらは、その定義の直前に記述されているか、あるいは \qmlproperty コマンドを使用して記述されている場合です。

QML 型 <TypeName> が、ネイティブ型として <ClassName> を指定してドキュメント化されています。<ClassName> を <OtherClass> に置き換えます

もし \nativetype コマンドが、同じドキュメント・プロジェクトに属する複数の QML 型のドキュメント・コメントで同じ引数とともに使用されている場合、QDoc はこの警告を出力します。これを解決するには、各 C++ クラスに対して\nativetype コマンドを 1 回だけ使用するようにしてください。

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 はファイルの解析を継続しますが、バッファに収まるトークンの部分のみが考慮されるため、出力が不完全になる可能性があります。

この警告を解決するには、該当するコンテンツのサイズを縮小する必要があります。可能であれば分割するか、一部を削除してください。

1つのトークンの最大文字数は、警告の横に表示されます。例：

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 コメントには、トピックコマンド（例：\module 、\page ）が含まれていません

QDoc コメントにトピックコマンドが含まれていない場合、QDoc はそのコメントが何を記述しているのか判別できず、この警告を出します。「このドキュメントを何にも関連付けることができません」と非常によく似ていますが、C++ ファイルや QML ファイルに含まれていないコメントに固有のものです。

<topic> は他のトピックコマンドと混在させることはできません

QDocでは、特定のユースケースにおいて、1つのドキュメントコメント内に複数のトピックコマンドを記述することが許可されています。異なるカテゴリに属する複数のトピックコマンドを使用すると、この警告が表示され、そのトピックからは出力が生成されません。

型が自身の基底型となっている: <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 では、関数やメソッドのドキュメントにすべてのパラメータを記述する必要があります。これは、ヘッダーファイル内の関数またはメソッドの宣言で指定されている各パラメータ名が、 \a コマンドの後に各パラメータ名（ヘッダーファイル内の関数またはメソッドの宣言で指定されているもの）が現れることによってこれを認識します。

この要件は、オーバーロードが \overload コマンドでマークされており、かつ同名の完全にドキュメント化された関数が存在する場合、関数のオーバーロードのドキュメントにはこの要件は適用されません。

未文書化のプロパティ '<name>'

この警告は、C++ クラスに、ドキュメントが欠落しているQ_PROPERTY 宣言があることを示しています。プロパティはクラスのパブリック API の一部であり、その目的、有効な値、および動作を記述するために、\property コマンドを使用したドキュメントが必要です。

<type> またはそのメンバーによって参照されている、ドキュメント化されていない QML <module>

QDocは、 \inqmlmodule または \qmlproperty コマンドに指定された識別子に基づいて QMLモジュールを見つけられない場合、この警告を発します。

これは、 \qmlmodule のドキュメントが欠落しているか、\qmlproperty 、\qmlmethod 、または\qmlsignal コマンドで誤ったモジュール識別子が使用されたことを意味します。

ドキュメント化されていない戻り値

戻り値の型が void ではない関数について、QDoc は戻り値がドキュメント化されているかどうかを確認します。関数またはメソッドのドキュメントに「return」で始まる単語が含まれていない場合、この警告が表示されます。

予期しない <end_command>

この警告は、例えば、 \endlist が、その前に \listがない場合などに発行されます。これは、ペアで現れるすべてのコマンド（例：startFoo/endFoo）に適用されます。

予期しない\snippet

QDocは、 \snippet コマンドで引用されたスニペットファイルを特定できない場合、QDocはこの警告を発します。

QML タイプ <type> のベース <name> が不明です

QML タイプの基底型として宣言された型名が見つからなかったか、または \inherits コマンドで宣言されていません。

不明なコマンド <name>

QDoc コメントで、バックスラッシュの後に QDoc の組み込みコマンドではなく、カスタムコマンドマクロとしても定義されていないトークンが続いている場合、QDoc はこの警告を出力します。コマンド名のスペルを確認し、カスタムコマンドの場合は、QDoc の設定にそれを定義する記述が含まれていないか確認してください。

また、QDoc コメント内でコードが引用されているためにこの警告が発生する場合もあります。例えば、作成者が C 文字列の終端文字 `'\0' ` や、`'\n' ` などの他の C 文字列エスケープシーケンスを、バックスラッシュをエスケープせずに参照していた場合などが考えられます。 ドキュメントにリテラルなバックスラッシュを含めるには、バックスラッシュを\ のようにエスケープするか、コード断片を\c{...} で囲んでください。これにより、バックスラッシュが QDoc コマンドの開始として解釈されるのを抑制できます。

不明なマクロ

QDoc は、バックスラッシュ (\) の後に、組み込みコマンドまたはユーザー定義マクロのいずれの名前としても認識できないトークンが続く場合、この警告を出力します。文字エスケープシーケンスを含むコードを引用する場合は、エスケープシーケンスに対するこの警告を防ぐために、コードを\c{...} で囲む必要があります。

<identifier> に対する認識できない QML モジュール/型修飾子

に渡しされたパラメータ \qmlproperty または \qmlmethod に渡されたパラメータに、どこにも定義されていない qmlModule::qmlType::identifier の組み合わせが含まれています。

例:

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

DragHandler には、DragAxis というプロパティがありません。

認識されないリストスタイル <name>

\listには、リストスタイルを変更するための単一の数値または文字というオプションの引数を指定できます。詳細については、{list-command}{\list} のドキュメントを参照してください。認識されない引数を使用すると、QDocはこの警告を発行します。

認識されないマークアップ言語

この警告は、\code コマンドに対して、QDocが認識しないプログラミング言語が指定された場合に発生します。例えば、このQMLコードブロックには無効な「QL」言語が指定されています：

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