リンクの作成

これらのコマンドは、クラス、関数、例、その他のターゲットへのハイパーリンクを作成するためのものです。

\l (リンク)

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

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

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

\l ：

• 外部ページ：

  An URL with a custom link text:
  \l {http://doc.qt.io/qt-6/} {Qt 6 Documentation}.
  
  An URL without a custom link text: \l {http://doc.qt.io/qt-6/}.

  としてレンダリングします：

  カスタムリンクテキストを含む URL：Qt 6 ドキュメント。

  カスタムリンクテキストなしのURL: http://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コマンドを使います。
• ドキュメント内の特定のアンカー・セクションリンク先は次のようになります：
  • セクションコマンドで指定されたセクションのタイトル：

    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コマンド。

  • コマンドで定義されたアンカー \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コマンドの主語。
• 例。ターゲットのリンクは例のタイトルか、コマンドで使われる相対パスです。 \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がリンク先を見つけられなかった場合に警告を発するようになります。さらに、関数名だけをリンクに表示させたい場合は、以下の構文を使うことができます：

• \l {QWidget::} {sizeHint()}

あいまいなリンクの修正

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

Qt C++ namespaceQDocがこのHTMLページを生成した時点では、このリンクは正しいものでした。そのリンクはまだC++名前空間に行っているのでしょうか？Qdocはこのlinkコマンドからリンクを生成しました：

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

Qt QML typeQDocがこのHTMLページを生成した時点では、このリンクも正しかったが、このリンク・コマンドを使わなければならなかった：

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

角括弧の中のQMLはQDocにターゲットがQMLページ上にある場合のみ、マッチするターゲットを受け入れるように指示します。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 が省略された場合、重複した名前のアタッチド・プロパティよりも、 通常のプロパティが優先してリンクされます。

この例では、QDocはQt C++名前空間ページを見つけるために角括弧引数を必要としませんでした。しかし、マッチするQMLターゲットが邪魔になったときにQDocにC++ターゲットを見つけさせるために、CPP を角括弧の引数として使うことができます。例えば、以下のリンクはQt QMLタイプを無視し、Qt C++ネームスペースにマッチするまでQDocに検索を続行させます。

• \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 コマンドは、ドキュメンテーション・ユニットの下部にある独立した "See also "セクションに表示されるリンクのリストを定義します。

このコマンドは、カンマで区切られたリンクのリストを引数にとります。行末がカンマの場合は、次の行にリストを続けることができます。一般的な構文は

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

QDocは自動的にプロパティの様々な関数を相互接続する "See also "リンクを生成しようとします。例えば、setVisible()関数は自動的にvisible()へのリンクを取得し、その逆も同様です。

一般的に、QDocは同じプロパティにアクセスする関数を相互接続する "See also "リンクを生成します。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 (link)と\sa (see also)コマンドを使ってリンクできるドキュメントの場所を指定します。

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

/*!
    \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 引数の\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 (link)と\sa (see also)コマンドを使ってリンクできるドキュメントの場所を指定します。また、生成されたインデックスにキーワードと場所を追加します。

\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}.
*/

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

\l (link),\sa (see also)および \target.