Ссылки в документации

Основная функция Scaladoc — создание API документации из комментариев к коду.

По умолчанию комментарии к коду понимаются как Markdown, хотя мы также поддерживаем старый Scaladoc синтаксис Wiki.

Синтаксис

Определение ссылок

Наш синтаксис определения ссылки очень близок к синтаксису Scaladoc, хотя мы внесли некоторые улучшения.

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

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

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

По умолчанию идентификатор id ссылается на первую (в исходном порядке) сущность с именем id. Идентификатор может заканчиваться на $, что заставляет его ссылаться на значение (объект, значение, given); идентификатор также может заканчиваться на !, что заставляет его ссылаться на тип (класс, псевдоним типа, член типа).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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