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

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

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

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

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

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

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