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

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

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

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