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

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

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