Связующая документация

Основной синтаксис

Определение ссылки выглядит следующим образом: [[scala.collection.immutable.List]]

.

Другими словами, определение ссылки представляет собой последовательность идентификаторов, разделенных знаком .

. Идентификаторы также могут быть разделены с помощью #

.

По умолчанию идентификатор id

ссылается на первую (в исходном порядке) сущность с именем id

. Идентификатор может заканчиваться на $

, что заставляет его ссылаться на значение (объект, значение, given); идентификатор также может заканчиваться на !

, что заставляет его ссылаться на тип (класс, псевдоним типа, член типа).

Ссылки разрешаются относительно текущего местоположения в источнике. То есть при документировании класса ссылки относятся к сущности, включающей класс (пакет, класс, объект); то же самое относится к документированию определений.

Специальные символы в ссылках могут быть экранированы обратной косой чертой, что вместо этого делает их частью идентификаторов. Например, [[scala.collection.immutable\.List]]

ссылается на класс immutable.List

, указанный в package scala.collection

.

Новый синтаксис

Определение ссылок Scaladoc было расширено, чтобы сделать их более удобными для записи и чтения в исходном коде. Также целью было сблизить связь и синтаксис Scala. Новые функции:

а) package

может использоваться в качестве префикса для ссылки на прилагаемый пакет. Пример:

 package utils
 class C {
   def foo = "foo"
 }
 /** See also [[package.C]]. */
 class D {
   def bar = "bar"
 }

Ключевое слово package

помогает сделать ссылки на прилагаемый пакет короче и немного более устойчивым к рефакторингу имен.

б) this

может использоваться в качестве префикса для ссылки на прилагаемый классоподобный пример:

class C {
  def foo = "foo"
  /** This is not [[this.foo]], this is bar. */
  def bar = "bar"
}

Использование здесь ключевого слова помогает сделать ссылки более привычными, а также помогает ссылкам пережить изменения имени класса.

в) Обратные кавычки могут использоваться для экранирования идентификаторов. Пример:

def `([.abusive.])` = ???
/** TODO: Figure out what [[`([.abusive.])`]] is. */
def foo = `([.abusive.])`

Ранее (версии 2.x) для ссылки на такие идентификаторы в Scaladoc требовалось экранирование обратной косой чертой. Теперь (версии 3.x) Scaladoc позволяет использовать знакомую обратную кавычку Scala.

Зачем сохранять синтаксис Wiki для ссылок?

Есть несколько причин, по которым синтаксис Wiki сохранен для ссылок на документацию вместо повторного использования синтаксиса Markdown. Это:

• Безымянные ссылки в Markdown уродливы: [](definition)
  против [[definition]]
  Безусловно, большинство ссылок в документации безымянные. Должно быть очевидно, как их писать.
• Поиск локального члена конфликтует с фрагментами URL: [](#field)
  против [[#field]]
• Разрешение перегрузки противоречит синтаксису MD: [](meth(Int))
  против [[meth(Int)]]
• Теперь, когда есть парсер для синтаксиса ссылок, можно разрешить пробелы внутри (в Scaladoc нужно было экранировать их косой чертой), но это не распознается как ссылка в Markdown: [](meth(Int, Float))
  против [[meth(Int, Float)]]

Ни одна из них не делает полностью невозможным использование стандартного синтаксиса ссылок Markdown, но они делают его гораздо более неуклюжим и уродливым, чем нужно. Кроме того, синтаксис ссылок Markdown даже не сохраняет никаких символов.

---

Ссылки:

• Scaladoc Guide