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

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

\l (ссылка)

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

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

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

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

Теперь предположим, что мы хотим установить ссылку на тип QML Qt. На момент генерации этой страницы 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 не потребовался аргумент в квадратных скобках для поиска страницы C++-пространства имён Qt, так как это был первый подходящий целевой объект, который QDoc обнаружил. Однако, чтобы принудительно заставить QDoc найти C++-целевой объект, когда на пути встречается соответствующий целевой объект QML, можно использовать CPP в качестве аргумента в квадратных скобках. Например:

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

...заставит QDoc проигнорировать тип Qt QML и продолжить поиск, пока не будет сопоставлен с пространством имен 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.