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

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

<ターゲット>にリンクできない

QDocは、ドキュメントのある部分（警告メッセージで特定される）が他の部分を参照しようとしたときにこの警告を出しますが、その他の部分、つまりリンクのターゲットが正しく指定されていません。これは、その参照先がミスタイプされていたり、（関数や型の）名前や（別のセクションの）タイトルが変更されていたりするために発生する可能性があります。

その特定のリンクターゲットについて、ソースコードを検索してください。結果が得られない場合は、一致するものが見つかるまで、徐々に検索を絞り込んでください。

リンク先が型や関数の名前に似ている場合、次のような原因が考えられます：

• ドキュメントで使用されている名前（関数の場合はシグネチャ）が、宣言で使用されている名前と一致しない。
• リンク先が \internalとしてマークされている。

テーブルの項目外で\target 。

QDocは\table...\endtable ブロック内で\li コマンドが先行しない\target コマンドに遭遇した場合、この警告を発します。警告の後には「この警告を解決するには、\target を\li の中に移動してください。

引用するスニペット・ファイルが見つかりません

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

これを修正するための便利なステップをいくつか紹介します：

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

予期しない\snippet

コマンドで引用されたスニペット・ファイルが見つからない場合、QDocはこの警告を発します。 \snippetコマンドで引用されたスニペットファイルが見つからない場合、QDocはこの警告を出します。

文書化されていないQMLの<module>が<type>またはそのメンバから参照されています。

に渡された識別子に基づいてQMLモジュールを特定できない場合、QDocはこの警告を表示します。 \inqmlmoduleまたは \qmlpropertyコマンドに渡された識別子から QML モジュールを見つけることができなかった場合、QDoc はこの警告を出します。

これは \qmlmoduleのドキュメントがないか、\qmlproperty 、\qmlmethod 、\qmlsignal のコマンドに不正なモジュール識別子が使われていることを意味します。

QML <module>にそのような<type>がありません。

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

QMLモジュール識別子が定義されている場合は、QML型ドキュメントの \inqmlmoduleQML型ドキュメントの引数と一致しなければなりません。ほとんどの場合、QDocはモジュール識別子がなくてもQML型の場所を特定することができます。

文書化されていない戻り値

戻り値が void でない関数の場合、QDoc はその戻り値が文書化されているかどうかをチェックします。この警告は関数やメソッドのドキュメントに "return "で始まる単語が含まれていない場合に出されます。

ドキュメント化されていないパラメータ

QDocは関数やメソッドのドキュメントにすべてのパラメーターを記述することを要求します。QDocは、各パラメータ名（関数またはメソッドがヘッダーファイルで宣言されている場所で指定されている）が \aコマンドの後に表示されることで、これを認識します。

この要件は関数のオーバーロードのドキュメントには課せられません。 \overloadコマンドでマークされ、同じ名前で完全に文書化された関数が存在する場合は、この要件は関数のオーバーロードの文書化には課されません。

そのようなパラメータはありません

コマンドの後に指定されたパラメータ名が \aコマンドの後に指定されたパラメータ名が、 ドキュメント化される関数やメソッドのヘッダーファイルの宣言で指定されたパラメータのどれとも一致しない場合に、QDocはこの警告を発します。

不明なマクロ

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

\fn <signature> を解析するときに関数を見つけられませんでした。

Clangが \fnコマンドに続く関数のシグネチャを解析するとき、ヘッダファイルの宣言と照合します。もしClangが矛盾を発見すると、この警告メッセージを出します。

シグネチャは完全に修飾されていなければなりません。典型的な問題には、テンプレート引数、戻り値型、constなどの修飾子の欠落や誤りがあります。

<parent> が文書化されていないため、<entity> の出力が生成されません。

QDoc は、クラス・メンバーなどの API エンティティのドキュメント・コメントを解析する際にこの警告を発しますが、関連する親（クラス）がドキュメント化されていないため、出力を生成できません。親がドキュメント化されており、ドキュメント・コメントを含むソース・ファイルを解析するように QDoc が構成されていることを確認してください。

ドキュメント化されたメンバが、ドキュメント化されることを意図していないクラスに属している場合は、そのクラスを \internalとしてマークするか \dontdocumentコマンドを使ってください。

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

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

このドキュメントを何かに結びつけることができません

QDoc は /*!*/ トピック・コマンドのない /*!そのため、このコメントが何を文書化しているのかがわかりません。

この qdoc のコメントにはトピックコマンドが含まれていません (例:\module,\page)。

QDocのコメントにトピックコマンドが含まれていない場合、QDocはそのコメントが何を文書化しているのかわからず、この警告を発します。Cannot tie this documentation to anythingとよく似ていますが、C++やQMLファイルにないコメント特有のものです。

<名前>が複数回文書化されている

QDocは同じ項目を文書化した2つのコメントを見つけると、この警告を発します。前に見たコメントの場所は警告の詳細に記載されています。

例えば、関数の定義の前にドキュメントのコメントがあり、別の場所に\fn 。

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

QDocでは、特定の使用例に対して、1つのドキュメント・コメントで複数のトピック・コマンドを使用することができます。異なるカテゴリから複数のトピック・コマンドを使用すると、この警告が出力され、トピックは出力を生成しません。

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

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

<name> はドキュメント化されているが、名前空間 <namespace> はどのモジュールにもドキュメント化されていない。

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

これは、<namespace>を文書化するか、他のモジュールで既に文書化されている場合は、このモジュールがそのモジュールに依存していることを確認することで解決できます。

dependsとindexes も参照してください。

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

QDocのコメントで、クラス、名前空間、ヘッダーファイルとモジュールとの関連が \inmoduleコマンドでモジュールに関連付けることができません。

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

Cannot find <name> specified with ˶<command> in any header file

これは、QDocがどのヘッダーファイルにも<name>の宣言を見つけることができないが、それを文書化すると主張するコメントを見つけたことを意味します。

例を挙げましょう：

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

ドキュメント・コメントはenumを記述していると主張しているが、QDocはそのenumの定義をヘッダー・ファイルで見つけられなかった。

これは次のような理由によるものかもしれません：

• <name> や <command> のタイプミス。
• 名前空間またはクラス接頭辞の欠落
• <name>が別の名前空間またはクラスに移動した。

<identifier>のQMLモジュール/型修飾子が認識できない。

パラメータ \qmlpropertyまたは \qmlmethodに渡されたパラメータが qmlModule::qmlType::identifier の組み合わせを含んでいる。

例

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

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

<name> のプロパティタイプがない

プロパティ \qmlpropertyの宣言にプロパティタイプがありません。

\qmlproperty コマンドは、プロパティ・タイプの後にプロパティの完全修飾名 (つまり、所属するクラス名の後に ::-joined という名前) が続くことを想定しています。

不正解：

\qmlproperty MyWidget::count

正しい：

\qmlproperty int MyWidget::count

文書化されていないプロパティ '<name>'

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

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

QDocは、同じQMLプロパティを文書化した2つのQDocコメントを見つけた場合にこの警告を表示します。 \qmlpropertyコマンドを使っている場合です。

コマンド <command> はQMLプロパティコマンドでは使用できません。

例

\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>であるプロパティ・グループをドキュメント化するために、1つのドキュメント・コメント内で複数のqmlpropertyまたはqmlattachedpropertyトピック・コマンドを許可します。他のトピック・コマンドはこの警告を誘発します。

<クラス>内の<メソッド>のベース関数が見つかりません。

QDocは、\reimp 、仮想メソッドのオーバーライドとしてメソッドをドキュメント化する際に、指定された名前とシグネチャを持つ仮想メソッドがベースクラスにない場合に、この警告を表示します。これは、オーバーライドするために書かれたメソッドのシグネチャが変更されたか、仮想メソッドでなくなったために起こる可能性があります。

Illegal\reimp; <command> のドキュメント化された仮想関数がありません。

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);

<class> は自分自身を継承しようとします。

この \inheritsコマンドはQMl型が他のQML型を継承していることを示すために使われます。この警告は他のQML型が文書化されたQML型と同じである場合に発せられます。

例

\qmltype Foo
\inherits Foo

\nativetype は\qmltype

この \nativetypeコマンドはQML型を文書化したQDocコメント内でのみ使用できます。

グループ内のすべてのプロパティは同じ型に属していなければなりません。

QMLプロパティ・グループを文書化する場合、コメント・ブロックにリストされているすべてのプロパティは同じQMLタイプに属していなければなりません。

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

サンプルのソース・ディレクトリで、QDoc はCMakeLists.txt という名前のプロジェクト・ファイルか、.pro 、.qmlproject 、.pyproject という拡張子を持つファイルが見つかることを期待しています。例えば、examples/mymodule/helloworld/helloworld.pro 。

引用元ファイルを開けません：<ファイル名

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

QDocはコマンドで指定されたファイル（例えば \quotefromfile, \snippet, \includeなど）で指定されたファイルが見つかりませんでした。QDocは検索パスで指定された各ディレクトリを検索します。これらのディレクトリのいずれにもこの名前のファイルがないか、ファイルは見つかったが読めない場合、QDocはこの警告を発します。検索パスと<filename>の組み合わせが正しいスペルであること、ファイルの読み取りパーミッションがあることを確認してください。

の後に書式名がない。\raw

コマンドと対応する \rawコマンドと対応する \endrawコマンドは生のマークアップ言語コードのブロックを区切ります。\raw コマンドの後に書式名を続けなければならない。

マクロは、書式固有の定義とqdoc-syntax定義の両方を持つことはできません。

A \macro出力フォーマットを指定するマクロは、一般的な定義も持つことはできません。

この警告を発生させるコンフィギュレーションの例：

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

不明なコマンド <名前

QDocのコメントでバックスラッシュの後にQDocの組み込みコマンドでもなく、カスタム・コマンド・マクロとしても定義されていないトークンが続くと、QDocはこの警告を出します。コマンド名のスペルをチェックし、QDocのコンフィギュレーションにそれがカスタム・コマンドとして定義されているものが含まれていないかチェックしてください。

この警告はQDocのコメントで引用されたコードが原因で発生することもあります。例えば、作者がバックスラッシュをエスケープせずに、C言語の文字列の終端文字'\0' 、または'\n' のような他のC言語の文字列のエスケープシーケンスの1つを参照した可能性があります。バックスラッシュを\ のようにエスケープして、ドキュメントにリテラルなバックスラッシュを含めるか、コード・フラグメントを\c{...} で囲んでください。

重複したターゲット名 <target

この警告は、同じパラメータで2つのターゲットを定義した場合に表示されます。 \targetまたは \keywordコマンドを使って定義した場合に表示されます。これらのコマンドのパラメータとして与えられるターゲット名は一意でなければなりません。警告の後には、"The previous occurrence is here：[location]」と続き、locationにはファイル名と行番号が入ります。

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

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

<file>に<tag>が見つかりません。

これはQDocが識別子<id>を \include<file> または {snippet-command}{\snippet} <file>で見つけることができないことを意味します。

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

スニペット <tag> は \snippet<file> に見つかったが、空である。

コマンドを入れ子にできない

この警告は書式コマンドに関係します: 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の警告 "Can't use '\table' in '\list'"。

<inner>の前に<outer>がない。

いくつかの例があります：

• コマンドは \liコマンドは \listまたは \rowの \table.
• と \rowと \headerコマンドは \table.

予期しない<end_command

この警告は、例えば、コマンドの前に \endlistの前に \list.この警告は2つ1組のコマンド（startFoo/endFooなど）に適用されます。

のコンマの欠落\sa

コマンドの \saコマンドはカンマで区切られるべきである。

マクロ<コマンド>にデフォルトの定義がありません。

QDocはマクロを展開しようとしており、そのマクロがデフォルト定義を持っていることを期待しています。マクロの中にはフォーマット固有の定義しか持たないものもあります。

例

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

しかし、マクロ展開がフォーマットに依存しないマクロを必要とする場合もあります。例えば、セクションタイトルにマクロを持つことができますが、それらはデフォルトの定義を持たなければなりません。

マクロ <macro> の引数が少なすぎる (expected <many>, got <few>)

指定されたマクロは、指定されたよりも多くのパラメータを必要とする。詳細はコンフィギュレーションのマクロ定義を参照のこと。

<text>の括弧がアンバランス

対応する')'がない'('、またはその逆を指す。

<name> のドキュメントがない

例

Warning "No documentation for QNativeInterface."

QDocはヘッダーファイルで名前空間QNativeInterface の宣言を検出しますが、その名前空間が文書化されているQDocコメントが見つかりません。

<class> にそのような enum 項目 <name> がありません。

例

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

QDocはこの警告を出します。 \valueディレクティブが \enumコメントで、その列挙型を宣言したヘッダファイルにない値を指定するディレクティブが見つかると、QDoc はこの警告を出します。

<enum list> 内の文書化されていない列挙項目 <enum> です。

<enum list> の \valueまたは \omitvalueの項目に、ヘッダファイルの <enum list> の宣言で指定されている<enum> の項目が含まれていませんでした。

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

Qtヘルププロジェクトの設定で<subproject>のインデックスページとして指定されたページのタイトルをQDocが見つけられませんでした。

サブプロジェクトのインデックスタイトルは、現在のドキュメントプロジェクトにローカルでなければなりません。依存関係としてロードされた他のプロジェクトのページタイトルを使用しても、この警告が表示されます。

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

\generatelist <グループ>が空です

のすべての引数の概要を以下に示します。 \generatelist:

• \generatelist 注釈付きサンプル
• \generatelist 注釈付き属性
• \generatelist classes <プレフィックス
• \generatelist classesbymodule <モジュール名>.
• \generatelist qmltypesbymodule <モジュール名> (英語)
• \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のコメントで追加されます。

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

画像がありません: <imagefile

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

<ターゲット>にリンクできません

これはさまざまな原因が考えられます：

• リンク先がQDocトピックコマンド（例：{title-command}{\title} <target>）で定義されていない。
• <target>にタイプミスがある。
• そのリンク・ターゲットを含むドキュメントがコンパイルされていません。
• そのリンクターゲットを含むドキュメントがコンパイルパスにないモジュールにある。
• リンク・ターゲットが別のモジュールにあり、そのモジュールへの依存関係がコンフィギュレーションに設定されていないか、QDoc が依存関係のインデックス・ファイルを見つけられませんでした。

型 <name> の QML import 文を解決できませんでした。

QDocがこの警告を出すのは、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

\brief 文の最後が完全なストップで終わっていません。

\brief コマンドの引数は、文書化されたトピックを要約する文章なので、完全なストップで終わるべきです。また、簡潔であるべきです。

QtDeclarativeがインストールされていません。

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 に渡され、1 つ以上に依存関係にマッチする.index ファイルが含まれていました。QDocは自動的に最新のタイムスタンプを持つものを選びます。

通常、この警告は以前のドキュメントのビルドからビルドの成果物が残っていることを示しています。

依存関係 <depend> のインデックスファイルが見つかりません。

例

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

ドキュメンテーションプロジェクトのQMakeは、指定されたインデックスディレクトリのいずれにもactiveqt.indexを見つけることができませんでした。この場合、指定されたインデックスディレクトリはqmake.qdocconfで指定されています。

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

QDocはコマンドラインに1つ以上の-indexdir引数があることを期待していました。これがないと、QDoc は 'depends' 設定変数で定義された依存モジュールのインデックスファイルを見つけることができません。

以前のdocを上書きする

QDocは同じ実体を記述しているように見える2つのコメントを見つけると、この警告を発します。前に見たコメントの場所は警告の詳細に記載されています。

認識できないリストスタイル <name

\listはオプションの引数を取ることができます: リストスタイルを変更する1つの数字または文字です。詳細は{list-command}{\list}のドキュメントを参照してください。認識されない引数を使った場合、QDocは次のような警告を出します。

Unable to parse QML snippet: <code> at line <y>, column <x>.

QDocのコメントにはQMLのコードを含めることができます。このコードはスニペットの中や、QDocコメントの中で \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 コマンドに置き換えて、この警告を抑制しても問題ないことが多いです。

コマンド <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はこのような警告を発します。

書き込みのために<ファイル>を開けませんでした

この警告は明らかに書き込みのためにファイルを開けなかったことを意味する。おそらくパスが間違っているか、あるディレクトリの書き込みパーミッションのせいだろう。

このページタイトルは複数のファイルに存在します

この \titleコマンドはページのタイトルを設定します。

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

QDocはあるタイトルが複数のページで使われている場合、この警告を出す。

内容が長すぎる

QDocはソース・ファイルをトークン化するときに固定サイズのバッファを使用します。ファイル内の1つのトークンが最大制限文字数を超えている場合、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.]

グローバル・スコープの関数 <name> に対してドキュメントが生成されない

QDoc は関数<name>のドキュメントをその宣言にマッチさせることができましたが、関数がグローバル名前空間で宣言されているため、出力が生成されませんでした。

そのため \relatesコマンドを使用して、関数を文書化された型、名前空間、またはヘッダーファイルと関連付けます。この関数は、関連付けられたリファレンス・ページに関連する非メンバとしてリストされます。

<project> のドキュメント設定がヘルププロジェクトを定義していない(qhp)

有効な Qt ヘルプ設定がプロジェクトの .qdocconf ファイルで提供されていません。

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

このプロジェクトのファイルがすでに生成されています。

プロジェクトのドキュメントを生成している間、QDoc は生成したファイルのファイル名を記録しています。QDocは書き込みのためにファイルを開くときに、そのファイルが現在の実行で以前に生成されたものであることが分かっている場合、警告を発します。これは \pageコマンドが \groupと同じ名前を使っている場合などに起こります。

環境変数QDOC_ALL_OVERWRITES_ARE_WARNINGS を設定することで、このようなイベントに対して無条件に警告を発することができる。これは問題のある定義を追跡するときに便利です。

無効なQMLプロパティタイプ

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

この警告は通常、開発者がQMLの型を実装するために使用したQtの基本型をlist<string> の代わりにQStringList のように参照した場合に発生します。

型はそれ自身の基底型である: <type

QMLの型が誤って自身の基底型として定義されています。 \inheritsコマンドを使っている可能性があります。

循環型継承: <type>

循環型継承は、QMLの型が基底型を継承し、その基底型が元の型を継承している場合に起こります。この現象は相互に継承しあう2つの型の間で起こることもあれば、その間に中間的な型が存在することもあります。

この警告は、継承階層内の循環が検出されたことを示しています。その型の \inheritsコマンドを調べ、以前に遭遇した型から継承される型が見つかるまで、ベースとなる型の軌跡をたどってください。そして、特定された型の1つについて、不正確なコマンドを修正することで、そのサイクルを断ち切らなければならない。 \inheritsコマンドを修正することで、このサイクルを断ち切らなければならない。

<name> の\sa コマンドにある self への冗長なリンク

コマンドで定義された参照に、自分自身へのリンクが含まれています。 \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)

Unknown base <name> for QML type <type>.

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

認識できないマークアップ言語

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

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