リンクの作成

これらのコマンドは、クラス、関数、例、およびその他の対象へのハイパーリンクを作成するためのものです。

\l (link)

\l リンクコマンドは、さまざまな種類のターゲットへのハイパーリンクを作成するために使用されます。このコマンドの一般的な構文は次のとおりです：

\l [ link criteria ] { link target } { link text }

...角括弧内の「link criteria 」は省略可能ですが、「link target 」が曖昧な場合には必要になる場合があります。詳細は、以下の「曖昧なリンクの修正」を参照してください。

\l コマンドを使用して、以下の対象へのリンクを作成できます:

外部ページ：
```
An URL with a custom link text:
\l {https://doc.qt.io/qt-6/} {Qt 6 Documentation}.

An URL without a custom link text: \l {https://doc.qt.io/qt-6/}.
```
表示結果は次のようになります：

カスタムリンクテキスト付きのURL：Qt 6 ドキュメント。

カスタムリンクテキストのないURL：https://doc.qt.io/qt-6/。

関連項目 \externalpage.
ドキュメントページ。リンク先は以下のいずれかになります：
- ` \title コマンドで指定されたページタイトル：
```
Here is a link with a custom link text:
\l {Getting Started with QDoc}{QDoc - Getting Started}.

Here is a link with a link text that is the same as the link
target: \l {Getting Started with QDoc}.
```
  表示結果は次のようになります:
  
  以下は、カスタムリンクテキストが設定されたリンクです：QDoc - はじめに。
  
  リンクテキストがリンク先と同じであるリンクの例：QDoc 入門。
- \page で指定されたページファイル名は次のとおりです：
```
\page 08-qdoc-commands-creatinglinks.html
\title Creating Links

These commands are for creating hyperlinks to classes, functions,
examples, and other targets.

...

The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
explains how to create links with QDoc.
```
  表示結果は次のようになります：
  
  「リンクの作成」ページの記事では、QDoc を使用してリンクを作成する方法について説明しています。
- 次の \keyword コマンドを含むページ。
ドキュメント内の特定のアンカーセクション。リンク先は次のいずれかです：
- Section コマンドのいずれかで指定されたセクションタイトル：
```
Here is a link to a QDoc Commands section of the Writing
Documentation topic:
\l {Writing Documentation#QDoc Commands}{QDoc Commands}.

If you have unique section titles across your documentation
project, you can use the section title as a target without
the need to add the topic title:
\l {QDoc Commands}.
```
  表示結果は次のようになります：
  
  以下は、「ドキュメントの作成」トピック内の「QDoc コマンド」セクションへのリンクです：QDoc コマンド。
  
  ドキュメントプロジェクト全体で固有のセクションタイトルがある場合は、トピックタイトル「QDoc コマンド」を追加することなく、セクションタイトルをターゲットとして使用できます。
  
  # という文字は、ドキュメント内でのリンクに使用されるため、この文字を含むタイトルへのリンクでは、そのまま使用することはできません。代わりに、バックスラッシュを使用してエスケープする必要があります：
```
\l {Using Qt with C\\#}
```
  QDocはテキストをリンクコマンドに渡す前に処理を行うため、バックスラッシュを2つ使用します。
- \target コマンドで定義されたアンカー：
```
\target assertions

Assertions make some statement about the text at the
point where they occur in the regexp, but they do not
match any characters.

...

Regexps are built up from expressions, quantifiers, and
\l {assertions} {assertions}.
```
API項目。ターゲットリンクは以下のいずれかです：
- \l QWidget - \class または \qmltype コマンドでドキュメント化されたクラスの名前。
- \l QWidget::sizeHint() - 引数を持たない関数のシグネチャ。引数を持たない一致する関数が見つからない場合、最初に一致した関数でリンクが成立します。
- \l QWidget::removeAction(QAction* action) - 引数を持つ関数のシグネチャ。完全に一致するものが見つからない場合、リンクは成立せず、QDocは「Can't link to...」エラーを報告します。
- \l <QtGlobal> - \headerfile コマンドの主語。
リンクに関数名のみを表示させたい場合は、次の構文を使用できます：\l{QWidget::}{sizeHint()} 。

例。ターゲットリンクは、例のタイトル、または \example コマンドで使用される相対パスです：

/*!
    \example widgets/imageviewer
    \title ImageViewer Example
    \brief Shows how to combine QLabel and QScrollArea
    to display an image.

    ...
*/

...

See the example: \l widgets/imageviewer

リンク先がリンクテキストと一致する場合は、2番目の引数を省略できます。

たとえば、次のようなドキュメントがある場合：

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.
*/

これを次のように簡略化できます：

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l assertions.
*/

1つのパラメータを取るバージョンでは、多くの場合、中括弧を省略できます。

自動リンク

QDoc は、通常の英語の単語とは似ていない単語（例えば、QWidget やQWidget::sizeHint() といった Qt のクラス名や関数名など）についても、リンクとして認識しようとします。このような場合、\l コマンドは実際には省略可能ですが、このコマンドを使用することで、リンク先が見つからない場合に QDoc が警告を出力するよう確実にすることができます。

自動リンクによって、たまたまリンク先と一致してしまった単語に対して不要なリンクが生成された場合は、`ignorewords` 設定変数を使用してそれを抑制することができます。

曖昧なリンクの修正

曖昧なリンクとは、複数の Qt モジュールやドキュメントセットに一致するリンク先が存在するリンクのことです。たとえば、同じセクションタイトルが複数の Qt モジュールに存在する場合や、あるモジュール内の C++ クラスの名前が、別のモジュール内の QML 型の名前でもある場合などです。Qt における実際の例としては、「Qt」という名前そのものが挙げられます。これは、QtCore 内の C++ 名前空間の名前であると同時に、QtQml 内の QML 型の名前でもあります。

Qt C++ namespace にリンクしたいと仮定しましょう。QDocがこのHTMLページを生成した時点では、そのリンクは正しく機能していました。今でもそのリンクはC++名前空間を指しているのでしょうか？QDocは、次のリンクコマンドからそのリンクを生成しました：

\l {Qt} {Qt C++ namespace}

次に、Qt QML type へのリンクを設定したいとします。QDocがこのHTMLページを生成した時点では、そのリンクも正しく機能していましたが、その際には次のlinkコマンドを使用する必要がありました：

\l [QML] {Qt} {Qt QML type}

角括弧内のQMLは、ターゲットがQMLページ上にある場合にのみ、一致するターゲットを受け入れるようQDocに指示しています。QDocは実際には最初にC++ネームスペースのターゲットを見つけますが、そのターゲットはC++ページ上にあるため、QDocはそれを無視し、QMLページ上で同じターゲットが見つかるまで検索を続けます。

オプションの角括弧引数内の\l コマンドによる指定がない場合、QDocは最初に見つかった一致するターゲットにリンクします。このような場合、QDocは別の一致するターゲットが存在することを認識していないため、リンクが曖昧であるという警告を出すことができません。

角括弧内にはどのような引数を指定できますか？

角括弧引数を持つリンクコマンドの構文は次のとおりです：

\l [QML|CPP|DOC|attached|QtModuleName] {link target} {link text}

角括弧の引数は、\l (link) コマンドでのみ使用できます。上記の例では、QML を角括弧の引数として使用し、QDocにQMLターゲットを照合させている様子を示しています。ほとんどの場合、これはQML型になりますが、QMLのメンバ関数やプロパティである場合もあります。また、一部のQML型には、同じ名前のプロパティとアタッチドプロパティが含まれています。アタッチドプロパティは、attached 引数を使用して指定できます。attached を省略した場合、名前が重複するアタッチドプロパティよりも、通常のプロパティが優先してリンクされます。

この例では、Qt C++ ネームスペースのページを見つけるために QDocに角括弧引数は必要ありませんでした。なぜなら、そのページが QDoc が最初に見つけた一致するターゲットだったからです。しかし、一致する QML ターゲットが邪魔になる場合に、QDoc に C++ ターゲットを強制的に検索させるには、角括弧引数として`CPP ` を使用できます。たとえば、次のリンクでは、QDocがQt Qml型を無視し、Qt C++名前空間に一致するまで検索を続けるように強制します。

\l [CPP] {Qt} {Qt C++ namespace}

リンク先が C++ でも QML エンティティでもない場合、角括弧引数として `DOC ` を使用することで、QDoc がこれらいずれにも一致しないようにすることができます。本稿執筆時点では、DOC の使用が必要となるような曖昧なリンクの事例はありませんでした。

多くの場合、ドキュメント作成者はリンク先がどの Qt モジュールにあるかを知っています。モジュール名がわかっている場合は、そのモジュール名を角括弧引数として使用します。上記の例で、Qt という名前の QML タイプがQtQml モジュールにあることがわかっている場合、リンクコマンドは次のように記述できます:

\l [QtQml] {Qt} {Qt QML type}

角括弧内の引数としてモジュール名が使用された場合、QDocはそのモジュール内のみを検索対象とします。これにより、リンク先の検索がより効率的になります。

最後に、モジュール名とエンティティ型の引数は、空白で区切って組み合わせることができるため、次のような記述も可能です:

\l [CPP QtQml] {Window} {C++ class Window}

本稿執筆時点では、この2つを組み合わせる必要があった事例はありませんでした。

関連項目 \sa、 \target、および \keyword。

\sa （関連項目）

\sa コマンドは、ドキュメントユニットの最下部にある独立した「関連項目」セクションに表示されるリンクのリストを定義します。

このコマンドは、カンマ区切りのリンク一覧を引数として受け取ります。行の末尾がカンマで終わっている場合は、次の行にリストを続けることができます。一般的な構文は次のとおりです:

\sa {the first link}, {the second link},
    {the third link}, ...

QDoc は、プロパティのさまざまな関数を相互に結びつける「関連項目」リンクを自動的に生成しようとします。たとえば、setVisible() 関数には自動的に visible() へのリンクが作成され、その逆も同様です。

一般的に、QDocは同じプロパティにアクセスする関数同士を相互に結びつける「関連項目」リンクを生成します。QDocは4種類の構文を認識します：

property()
setProperty()
isProperty()
hasProperty()

\sa コマンドは、 \l コマンドと同様のリンクをサポートしています。

/*!
    Appends the actions \a actions to this widget's
    list of actions.

    \sa removeAction(), QMenu, addAction()
*/
void QWidget::addActions(QList<QAction *> actions)
{
    ...
}

関連項目 \l、 \target および \keyword。

\target

\target コマンドは、ドキュメント内の特定の箇所を指定するもので、\l （リンク）および\sa （関連項目）コマンドを使用して、その箇所へのリンクを設定できます。

改行までのテキストがターゲット名となります。ターゲット名の後には必ず改行を入れてください。ターゲット名の前後で中括弧を付ける必要はありませんが、リンクコマンド内でターゲット名を使用する場合は必要になる場合があります。詳細は以下を参照してください。

/*!
    \target capturing parentheses
    \section1 Capturing Text

    Parentheses allow us to group elements together so that
    we can quantify and capture them.

    ...
*/

ターゲット名の括弧は、次のようにリンク設定できます：

\l {capturing parentheses}

上記では、ターゲット名にスペースが含まれているため、角括弧で囲まれています。

注： \target コマンドは 、 macro 引数内の展開はサポートされていません。

\target in a\table

テーブル内で\target コマンドを使用する場合は、\target コマンドが \li-コマンド（表のセル）の直後に配置されていることを確認してください。一部のジェネレータは、行全体ではなく個々のセルへの指定のみをサポートしているためです。さらに、そのコマンドが別の行にあるか、あるいはその行内で最後のコンテンツとなっていることを確認してください。これは、\target コマンドの動作によるものです。このコマンドは、次の改行までのすべての内容をパラメータとして処理します。つまり、表の中に\target を挿入する必要がある場合は、以下の構造に従うようにしてください：

\table
    \row
        \li \target my-target
        My text goes here.
        \li This is my next table cell.
\endtable

関連項目 \l, \sa および \keyword。

\keyword

\keyword コマンドは、ドキュメント内の特定の箇所を指定するもので、この箇所へは\l （リンク）および\sa （関連項目）コマンドを使用してリンクを設定できます。また、生成される索引にキーワードとその場所を追加します。

\keyword コマンドは \target コマンドと似ていますが、キーワードへのリンクを設定する場合、デフォルトでは、そのリンクが\keyword が含まれるQDocコメント（トピック）の先頭へ移動する点が異なります。

トピック内のsection ユニット用のキーワードを作成したい場合は、セクションタイトルの直上に\keyword を追加してください：

\keyword debug
\section1 Debug command line option (--debug)
...

\target とは異なり、キーワードは生成されたオフラインドキュメントファイル（.qch）の索引に登録されます。これにより、ユーザーは例えばQt Assistant の「索引検索」でキーワードから場所を検索できるようになり、Qt Creator のコンテキストヘルプでもそのキーワードを利用できるようになります。

キーワードは、QDocの実行中に処理されるすべてのドキュメントを通じて一意である必要があります。このコマンドは、行の残りの部分を引き数として使用します。キーワードの後に必ず改行を入れてください。

/*!
    \class QRegularExpression
    \reentrant
    \brief The QRegularExpression class provides pattern
           matching using regular expressions.
    \ingroup tools
    \ingroup misc
    \ingroup shared

    \keyword regular expression

    Regular expressions, or "regexps", provide a way to
    find patterns within text.

    ...
*/

キーワードでマークされた位置には、次のようにリンクを設定できます：

/*!
    When a string is surrounded by slashes, it is
    interpreted as a \l {regular expression}.
*/

キーワードのテキストにスペースが含まれる場合は、角括弧が必要です。

注： \keyword コマンドは 、 macro 引数内の展開をサポートしていません。

関連項目：\l （リンク）、\sa （関連項目）、および \targetを参照してください。

外部コードの組み込み画像の組み込み

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.