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

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

Определение ссылки выглядит следующим образом: [[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