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

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

\l (ссылка)

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

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

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

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

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

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

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

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

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

/ *!
   \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, вероятность столкновения с неоднозначными ссылками увеличилась. Неоднозначная ссылка — это ссылка, у которой существует несколько соответствующих целевых объектов в разных модулях Qt, например, одинаковое название раздела может встречаться в нескольких модулях Qt, или имя класса C++ в одном модуле может совпадать с именем типа QML в другом модуле. Реальный пример в Qt5 — имя Qt. Qt — это имя как пространства имен C++ в QtCore, так и типа QML в QtQml.

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

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

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

• \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 используется в качестве аргумента в квадратных скобках, чтобы заставить qdoc сопоставить целевой объект QML. Чаще всего это тип QML, но это также может быть функция члена QML или свойство.

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

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

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

Если целевой объект ссылки не является ни объектом 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 QRegExp
    \reentrant
    \brief The QRegExp 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 {QRegExp}{regular expression}.
* /

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

Если строка заключена в косые черты, она интерпретируется как регулярное выражение.

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

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