Создание ссылок

Эти команды предназначены для создания гиперссылок на классы, функции, примеры и другие целевые объекты.

\l (ссылка)

Команда \l link используется для создания гиперссылки на различные целевые объекты. Общий синтаксис команды:

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

… где link criteria в квадратных скобках являются необязательными, но могут быть необходимыми, когда link target является неоднозначной. См. Устранение неоднозначностей в ссылках ниже.

Вот пример использования команды \l для ссылки на внешнюю страницу:

/ *!
   Read the \l {http://doc.qt.io/qt-6/}
   {Qt 6 Documentation} carefully.
* /

QDoc отображает это как:

Внимательно прочитайте документацию Qt 6.

Если целевой объект ссылки эквивалентен тексту ссылки, второй аргумент можно опустить.

Например, если у вас есть документация, подобная:

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

В версии с одним параметром фигурные скобки часто можно опустить. Команда \l поддерживает несколько способов создания ссылок:

• \l QWidget — имя класса, документированного с помощью команды \class.
• \l QWidget::sizeHint() — сигнатура функции без параметров. Если соответствующая функция без параметров не найдена, ссылка удовлетворяется первой найденной соответствующей функцией.
• \l QWidget::removeAction(QAction* action) — сигнатура функции с параметрами. Если точное совпадение не найдено, ссылка не удовлетворяется, и QDoc выводит ошибку Невозможно создать ссылку на….
• \l <QtGlobal> — тема команды \headerfile.
• \l widgets/wiggly — относительный путь, используемый в команде \example.
• \l {QWidget Class Reference} — заголовок, используемый в команде \title.
• \l {Introduction to QDoc} — текст из одной из команд разделов.
• \l fontmatching — аргумент команды \target.
• \l {Shared Classes} — ключевое слово, указанное в команде \keyword.
• \l http://qt-project.org/ — URL.

QDoc также пытается создать ссылку для любого слова, которое не напоминает обычное английское слово, например, имена классов Qt или функций, как QWidget или QWidget::sizeHint(). В этих случаях команда \l может быть фактически опущена, но с помощью команды вы гарантируете, что QDoc выведет предупреждение, если целевой объект ссылки не будет найден. Кроме того, если вы хотите, чтобы только имя функции отображалось в ссылке, вы можете использовать следующий синтаксис:

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

QDoc отображает это как:

sizeHint()

Устранение неоднозначностей в ссылках

Из-за модулизации Qt, начиная с Qt 5.0, возросла вероятность того, что QDoc столкнется с неоднозначными ссылками. Неоднозначная ссылка — это ссылка, имеющая соответствующий целевой объект в более чем одном модуле Qt, например, одно и то же название раздела может встречаться в более чем одном модуле Qt, или имя C++-класса в одном модуле может также быть именем типа QML в другом модуле. Реальный пример в Qt5 — имя Qt. Qt — это имя как C++-пространства имен в QtCore, так и типа QML в QtQml.

Предположим, мы хотим создать ссылку на C++-пространство имен Qt. На момент генерации QDoc этой страницы HTML эта ссылка была правильной. Все еще ведет ли она к пространству имен C++? Qdoc сгенерировал эту ссылку из следующей команды:

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

Теперь предположим, что мы хотим создать ссылку на тип QML Qt. На момент генерации QDoc этой страницы HTML эта ссылка также была правильной, но нам пришлось использовать эту команду:

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

QML в квадратных скобках сообщает QDoc принять соответствующий целевой объект только в том случае, если целевой объект находится на странице QML. Qdoc фактически находит целевой объект C++-пространства имен в первую очередь, но поскольку этот целевой объект находится на странице C++, QDoc игнорирует его и продолжает поиск, пока не найдет тот же целевой объект на странице QML.

Без указания в команде \l в необязательном аргументе в квадратных скобках QDoc создает ссылку на первый найденный соответствующий целевой объект. QDoc не может предупредить о том, что ссылка была неоднозначной в таких случаях, потому что не знает о существовании другого соответствующего целевого объекта.

Какие аргументы могут появляться в квадратных скобках?

Команда ссылки с аргументом в квадратных скобках имеет следующий синтаксис:

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

Аргумент в квадратных скобках разрешен только в команде \l (link). Приведенный выше пример демонстрирует, как QML используется в качестве аргумента квадратных скобок для принудительного сопоставления целевого объекта QML. Чаще всего это будет тип QML, но это также может быть членская функция или свойство QML.

В примере QDoc не потребовался аргумент в квадратных скобках для поиска страницы Qt-пространства имен C++, потому что это был первый соответствующий целевой объект, который QDoc нашел. Однако для принудительного поиска C++-целевого объекта, когда соответствующий целевой объект QML встречается на пути, можно использовать CPP в качестве аргумента квадратных скобок. Например:

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

… заставит QDoc проигнорировать тип QML Qt и продолжить поиск, пока не будет найдено пространство имен C++ Qt.

Если целевой объект ссылки не является ни C++-, ни QML-сущностью, DOC может быть использован в качестве аргумента квадратных скобок, чтобы предотвратить соответствие QDoc ни одному из них. На момент написания этой статьи случаев неоднозначных ссылок, в которых требовалось использование DOC, не было.

Часто разработчик документа знает, в каком модуле Qt находится целевой объект ссылки. При известном имени модуля используйте его в качестве аргумента квадратных скобок. В примере выше, если нам известно, что тип QML под названием Qt находится в модуле QtQml, мы можем записать команду ссылки следующим образом:

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

Когда имя модуля используется в качестве аргумента квадратных скобок, QDoc будет искать целевой объект только в этом модуле. Это делает поиск целевых объектов ссылок более эффективным.

Наконец, имя модуля и аргументы типа сущности могут быть объединены, разделенные пробелом, поэтому допускается и такой синтаксис:

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

На момент написания этой статьи случаев, когда комбинирование обоих аргументов было необходимо, не было.

См. также \sa, \target и \keyword.

\sa (см. также)

Команда \sa определяет список ссылок, которые будут отображаться в отдельном разделе «См. также» в нижней части документа.

Команда принимает список ссылок, разделенных запятыми. Если строка заканчивается запятой, вы можете продолжить список в следующей строке. Общий синтаксис:

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

QDoc автоматически попытается сгенерировать ссылки «См. также», соединяющие различные функции свойства. Например, функция setVisible() автоматически получит ссылку на функцию visible() и наоборот.

В общем случае QDoc сгенерирует ссылки «См. также», соединяющие функции, которые обращаются к одному и тому же свойству. Он распознает четыре различные версии синтаксиса:

• 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)
{
...
}

QDoc отображает это как:

void QWidget::addActions ( QList<QAction*> actions )

Добавляет действия actions в список действий этого виджета.

См. также removeAction(), QMenu и addAction().

См. также \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} (изнутри того же комментария QDoc)

Примечание: Скобки в примере ссылки необходимы, так как имя целевого объекта содержит пробелы.

См. также \l, \sa и \keyword.

\keyword

Команда \keyword задает имя места в документации, к которому можно обратиться с помощью команд \l (ссылка) и \sa (см. также).

Команда \keyword похожа на команду \target, за исключением того, что при ссылке на ключевое слово ссылка переходит в начало комментария QDoc, где появляется \keyword. Если вы хотите создать целевой объект ссылки на section блок в \page, используйте \target вместо этого. Ключевое слово можно связать от любого места с помощью простого синтаксиса.

Ключевые слова должны быть уникальными во всех документах, обработанных во время выполнения 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 {QRegularExpression}{regular expression}.
* /

QDoc отображает это как:

Когда строка окружена косыми чертами, она интерпретируется как регулярное выражение.

Если текст ключевого слова содержит пробелы, скобки необходимы.

См. также \l (ссылка), \sa (см. также) и \target.