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

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

\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. В момент генерации этой страницы 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 найти 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 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.