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

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

\l (ссылка)

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

\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 ссылка была корректной. Она всё ещё ведёт в пространство имён 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 не потребовался аргумент квадратных скобок для поиска страницы пространства имён 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}

См. также \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.