diff --git a/_includes/sidebar-toc-singlepage-overview.html b/_includes/sidebar-toc-singlepage-overview.html
index 7b2e68e995..020a98bc22 100644
--- a/_includes/sidebar-toc-singlepage-overview.html
+++ b/_includes/sidebar-toc-singlepage-overview.html
@@ -12,10 +12,10 @@
Contents
{% assign lang = site.data.languages[l] %}
{{ lang.name }}
{% endfor %}
-
+
{% elsif page.language %}
{% assign engPath = page.id | remove_first: "/" | remove_first: page.language | append: '.html' %}
- {% assign engPg = site.documents | where: 'partof', page.partof | first %}
+ {% assign engPg = site.overviews | where: 'partof', page.partof | first %}
- English
{% for l in engPg.languages %}
diff --git a/_overviews/scala3-scaladoc/blog.md b/_overviews/scala3-scaladoc/blog.md
index 612ee5c25e..be9754820c 100644
--- a/_overviews/scala3-scaladoc/blog.md
+++ b/_overviews/scala3-scaladoc/blog.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Built-in blog
partof: scala3-scaladoc
+languages: ["ru"]
num: 5
previous-page: static-site
next-page: site-versioning
diff --git a/_overviews/scala3-scaladoc/docstrings.md b/_overviews/scala3-scaladoc/docstrings.md
index 5efb8b5f38..f1036b3d29 100644
--- a/_overviews/scala3-scaladoc/docstrings.md
+++ b/_overviews/scala3-scaladoc/docstrings.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Docstrings - specific Tags and Features
partof: scala3-scaladoc
+languages: ["ru"]
num: 2
previous-page: index
next-page: linking
@@ -187,9 +188,9 @@ Concise is nice! Get to the point quickly, people have limited time to spend on
Omit unnecessary words. Prefer returns X rather than this method returns X, and does X,Y & Z rather than this method does X, Y and Z.
DRY - don’t repeat yourself. Resist duplicating the method description in the @return tag and other forms of repetitive commenting.
-More details on writing Scaladoc
+### More details on writing Scaladoc
-Further information on the formatting and style recommendations can be found in Scala-lang scaladoc style guide.
+Further information on the formatting and style recommendations can be found in [Scala-lang scaladoc style guide](https://docs.scala-lang.org/style/scaladoc.html).
## Linking to API
diff --git a/_overviews/scala3-scaladoc/index.md b/_overviews/scala3-scaladoc/index.md
index b158e9d89e..c00475f4ba 100644
--- a/_overviews/scala3-scaladoc/index.md
+++ b/_overviews/scala3-scaladoc/index.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Scaladoc
partof: scala3-scaladoc
+languages: ["ru"]
num: 1
next-page: docstrings
---
diff --git a/_overviews/scala3-scaladoc/linking.md b/_overviews/scala3-scaladoc/linking.md
index 635c461abd..05301d8f85 100644
--- a/_overviews/scala3-scaladoc/linking.md
+++ b/_overviews/scala3-scaladoc/linking.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Linking documentation
partof: scala3-scaladoc
+languages: ["ru"]
num: 3
previous-page: docstrings
next-page: static-site
diff --git a/_overviews/scala3-scaladoc/search-engine.md b/_overviews/scala3-scaladoc/search-engine.md
index 88a7b1a31b..612972811f 100644
--- a/_overviews/scala3-scaladoc/search-engine.md
+++ b/_overviews/scala3-scaladoc/search-engine.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Type-based search
partof: scala3-scaladoc
+languages: ["ru"]
num: 7
previous-page: site-versioning
next-page: snippet-compiler
diff --git a/_overviews/scala3-scaladoc/settings.md b/_overviews/scala3-scaladoc/settings.md
index 8cdb164aac..6b062967f2 100644
--- a/_overviews/scala3-scaladoc/settings.md
+++ b/_overviews/scala3-scaladoc/settings.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Settings
partof: scala3-scaladoc
+languages: ["ru"]
num: 9
previous-page: snippet-compiler
---
@@ -52,19 +53,18 @@ Example source links is:
Accepted formats:
-\=\
-\
+`=`
-where \ is one of following:
+where `` is one of following:
- `github:///[/revision][#subpath]`
will match https://github.com/$organization/$repository/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber]
when revision is not provided then requires revision to be specified as argument for scaladoc
- `gitlab:///`
will match https://gitlab.com/$organization/$repository/-/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber]
when revision is not provided then requires revision to be specified as argument for scaladoc
- - \
+ - ``
-\ is a format for `doc-source-url` parameter from old scaladoc.
+`` is a format for `doc-source-url` parameter from old scaladoc.
NOTE: We only supports `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`,
`€{FILE_PATH}`, and `€{FILE_LINE}` patterns.
@@ -81,7 +81,7 @@ Mapping between regexes matching classpath entries and external documentation.
Example external mapping is:
`-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/`
-A mapping is of the form '\::\[scaladoc3|scaladoc|javadoc]::\'. You can supply several mappings, separated by commas, as shown in the example.
+A mapping is of the form `::[scaladoc3|scaladoc|javadoc]::`. You can supply several mappings, separated by commas, as shown in the example.
##### -social-links
@@ -89,7 +89,7 @@ Links to social sites. For example:
`-social-links:github::https://github.com/lampepfl/dotty,discord::https://discord.com/invite/scala,twitter::https://twitter.com/scala_lang`
-Valid values are of the form: `\[github|twitter|gitter|discord]::link`. Scaladoc also supports `custom::link::white_icon_name::black_icon_name`. In this case icons must be present in `images/` directory.
+Valid values are of the form: `[github|twitter|gitter|discord]::link`. Scaladoc also supports `custom::link::white_icon_name::black_icon_name`. In this case icons must be present in `images/` directory.
##### -skip-by-id
@@ -156,9 +156,9 @@ where `path` is a prefix of the path to source files where snippets are located
If the path is not present, the argument will be used as the default for all unmatched paths.
Available flags:
-compile - Enables snippet checking.
-nocompile - Disables snippet checking.
-fail - Enables snippet checking, asserts that snippet doesn't compile.
+- compile - Enables snippet checking.
+- nocompile - Disables snippet checking.
+- fail - Enables snippet checking, asserts that snippet doesn't compile.
The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page]({{ site.scala3ref }}/other-new-features/opaques.html)
@@ -168,9 +168,9 @@ Example usage:
Which means:
-all snippets in files under directory `my/path/nc` should not be compiled at all
-all snippets in files under directory `my/path/f` should fail during compilation
-all other snippets should compile successfully
+- all snippets in files under directory `my/path/nc` should not be compiled at all
+- all snippets in files under directory `my/path/f` should fail during compilation
+- all other snippets should compile successfully
##### -Ysnippet-compiler-debug
diff --git a/_overviews/scala3-scaladoc/site-versioning.md b/_overviews/scala3-scaladoc/site-versioning.md
index d15fc49ab3..910b1f77ce 100644
--- a/_overviews/scala3-scaladoc/site-versioning.md
+++ b/_overviews/scala3-scaladoc/site-versioning.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Site versioning
partof: scala3-scaladoc
+languages: ["ru"]
num: 6
previous-page: blog
next-page: search-engine
diff --git a/_overviews/scala3-scaladoc/snippet-compiler.md b/_overviews/scala3-scaladoc/snippet-compiler.md
index b89c81da76..77c9497d98 100644
--- a/_overviews/scala3-scaladoc/snippet-compiler.md
+++ b/_overviews/scala3-scaladoc/snippet-compiler.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Snippet checking
partof: scala3-scaladoc
+languages: ["ru"]
num: 8
previous-page: search-engine
next-page: settings
diff --git a/_overviews/scala3-scaladoc/static-site.md b/_overviews/scala3-scaladoc/static-site.md
index a297c9a1e0..df36e95557 100644
--- a/_overviews/scala3-scaladoc/static-site.md
+++ b/_overviews/scala3-scaladoc/static-site.md
@@ -2,6 +2,7 @@
layout: multipage-overview
title: Static documentation
partof: scala3-scaladoc
+languages: ["ru"]
num: 4
previous-page: linking
next-page: blog
diff --git a/_ru/scala3/contribute-to-docs.md b/_ru/scala3/contribute-to-docs.md
new file mode 100644
index 0000000000..a96a1a0fa6
--- /dev/null
+++ b/_ru/scala3/contribute-to-docs.md
@@ -0,0 +1,68 @@
+---
+layout: singlepage-overview
+title: Вклад в документацию
+partof: scala3-scaladoc
+scala3: true
+language: ru
+---
+
+## Обзор
+В настоящее время предпринимается множество усилий по созданию высококачественной документации для Scala 3.
+В частности, это следующие документы:
+
+- Книга Scala 3
+- Учебник по макросам
+- Руководство по миграции
+- Справочник по языку Scala 3
+
+Мы приветствуем вклад сообщества в каждый аспект документации.
+
+
+### Как я могу внести свой вклад?
+В целом, есть много способов, которыми вы можете нам помочь:
+
+- **Запутались в чем-то в любом из документов?** Откройте issue.
+- **Нашли что-то неактуальное?** Откройте issue или создайте PR.
+- **Опечатки и другие мелкие улучшения текста?** Создайте PR.
+- **Хотите добавить что-то новое или внести большие изменения?** Отлично! Пожалуйста, откройте issue и давайте обсудим это.
+
+Как правило, каждый из различных проектов документации содержит ссылки
+(как и этот документ на панели оглавления — пока видимые только в desktop view) для их редактирования и улучшения.
+Кроме того, ниже мы предоставим вам всю необходимую информацию для начала работы.
+
+
+## Книга Scala 3
+[Книга Scala 3][scala3-book] написана Alvin Alexander и содержит обзор всех важных функций Scala 3.
+Она предназначена для читателей, которые только знакомятся со Scala.
+
+- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-book)
+- [Вопросы](https://github.com/scala/docs.scala-lang/issues)
+
+## Учебник по макросам
+[Учебник по макросам](/scala3/guides/macros) написан Nicolas Stucki и содержит подробную информацию о макросах в Scala 3 и best-practices.
+
+- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-macros)
+- [Вопросы](https://github.com/scala/docs.scala-lang/issues)
+
+## Руководство по миграции
+[Руководство по миграции на Scala 3](/scala3/guides/migration/compatibility-intro.html) содержит исчерпывающий обзор
+совместимости между Scala 2 и Scala 3, презентацию по инструментам миграции и подробные руководства по миграции.
+
+- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration)
+- [Вопросы](https://github.com/scala/docs.scala-lang/issues)
+
+## Руководство по содействию в разработке Scala 3
+[Руководство по содействию в разработке Scala 3](/scala3/guides/contribution/contribution-intro.html)
+содержит исчерпывающий обзор вклада в разработку и внутреннего устройства компилятора и библиотек Scala 3.
+
+- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution)
+- [Вопросы](https://github.com/scala/docs.scala-lang/issues)
+
+## Справочник по языку Scala 3
+[Справочник по Scala 3]({{ site.scala3ref }}) содержит формальное представление и подробную техническую информацию о различных возможностях языка.
+
+- [Исходники](https://github.com/lampepfl/dotty/tree/main/docs/_docs)
+- [Вопросы](https://github.com/lampepfl/dotty/issues)
+
+
+[scala3-book]: {% link _overviews/scala3-book/introduction.md %}
diff --git a/_ru/scala3/guides/scaladoc/blog.md b/_ru/scala3/guides/scaladoc/blog.md
new file mode 100644
index 0000000000..d631dde80f
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/blog.md
@@ -0,0 +1,35 @@
+---
+layout: multipage-overview
+title: Встроенный блог
+partof: scala3-scaladoc
+language: ru
+num: 5
+previous-page: static-site
+next-page: site-versioning
+---
+
+Scaladoc позволяет включить в документацию простой блог.
+На данный момент предоставляются только основные функции.
+В будущем мы планируем включить более продвинутые функции, такие как теги или авторские страницы.
+
+К блогу относятся немного иначе, чем к обычным статическим сайтам.
+Эта статья поможет вам создать свой собственный блог.
+
+## Правильная настройка каталога
+
+Сообщения в блоге должны быть помещены в каталог `_blog/_posts`.
+
+
+```
+├── _blog
+│ ├── _posts
+│ │ └── 2016-12-05-implicit-function-types.md
+│ └── index.html
+```
+
+Scaladoc загружает блог, если существует каталог `_blog`.
+
+## Соглашение об именовании
+
+Все имена файлов сообщений блога должны начинаться с даты в числовом формате, соответствующем `YYYY-MM-DD`.
+Пример имени - `2022-06-17-dotty-compiler-bootstraps.md`.
diff --git a/_ru/scala3/guides/scaladoc/docstrings.md b/_ru/scala3/guides/scaladoc/docstrings.md
new file mode 100644
index 0000000000..c537b39da6
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/docstrings.md
@@ -0,0 +1,222 @@
+---
+layout: multipage-overview
+title: Docstrings - специфичные теги и особенности
+partof: scala3-scaladoc
+language: ru
+num: 2
+previous-page: index
+next-page: linking
+---
+
+В этой главе описывается, как правильно писать строки документации и как использовать все доступные функции scaladoc.
+Так как многое осталось таким же, как и в старом scaladoc, некоторые детали взяты из этой
+[статьи](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html).
+
+Scaladoc расширяет возможности Markdown дополнительными функциями, такими как ссылки на определения API.
+Это можно использовать в статической документации и постах в блогах для создания смешанного контента.
+
+## Куда поместить строки документации
+
+Комментарии Scaladoc идут перед элементами, к которым они относятся, в специальном блоке комментариев,
+который начинается с `/**` и заканчивается `*/`, например:
+
+```scala
+/** Комментарий начинается здесь.
+ * Левая "звезда", за которой следует пробел в каждой строке,
+ * позволяет продолжить комментарий.
+ *
+ * Даже на пустых строках разрыва абзаца.
+ *
+ * Обратите внимание, что '*' в каждой строке выровнена
+ * со вторым '*' в '/**' так, чтобы
+ * левое поле находилось в том же столбце, где
+ * первая строка и последующие.
+ *
+ * Комментарий закрывается с помощью '*' и обратного слэша.
+ *
+ * Если используются теги Scaladoc (@param, @group и т.д.),
+ * не забудьте поместить их в отдельные строки без предшествующих им строк.
+ *
+ * Например:
+ *
+ * Рассчитать квадрат заданного числа
+ *
+ * @param d the Double to square
+ * @return the result of squaring d
+ */
+ def square(d: Double): Double = d * d
+```
+
+В приведенном выше примере этот комментарий Scaladoc связан с методом square,
+поскольку он находится прямо перед ним в исходном коде.
+
+Комментарии Scaladoc могут идти перед полями, методами, классами, трейтами, объектами.
+На данный момент scaladoc не поддерживает прямое решение для документирования пакетов.
+На гитхабе есть специальный [issue](https://github.com/lampepfl/dotty/issues/11284), где вы можете проверить текущий статус проблемы.
+
+Для первичных конструкторов класса, которые в Scala совпадают с определением самого класса,
+тег @constructor используется для указания комментария, помещаемого в документацию первичных конструкторов, а не в обзор класса.
+
+## Теги
+
+Scaladoc использует теги `@`для предоставления определенных подробностей полей в комментариях.
+Теги включают:
+
+### Теги, специфичные для класса
+
+- `@constructor` помещенный в комментарий класса, будет описывать первичный конструктор.
+
+### Теги, специфичные для метода
+
+- `@return` для детализации возвращаемого значения из метода (по одному на метод).
+
+### Теги метода, конструктора и/или класса
+
+- `@throws` какие исключения (если есть) может генерировать метод или конструктор.
+- `@param` детализация параметра метода или конструктора, предоставляется по одному `@param` для каждого параметра метода/конструктора.
+- `@tparam` детализация параметра типа для метода, конструктора или класса. Указывается по одному для каждого параметра типа.
+
+### Теги использования
+
+- `@see` ссылки на другие источники информации, такие как ссылки на внешние документы или связанные объекты в документации.
+- `@note` добавление примечания о предварительных или последующих условиях или любых других заметных ограничениях или ожиданиях.
+- `@example` предоставление примера кода или соответствующей документации.
+
+
+### Теги группировки
+
+Эти теги хорошо подходят для больших типов или пакетов со многими элементами.
+Они позволяют организовать страницу Scaladoc в отдельные разделы, каждый из которых отображается отдельно в выбранном порядке.
+
+Эти теги не включены по умолчанию! Необходимо передать флаг `-groups` в Scaladoc, чтобы включить их.
+В sbt это обычно выглядит примерно так:
+
+```scala
+Compile / doc / scalacOptions ++= Seq(
+ "-groups"
+)
+```
+
+Каждый раздел должен иметь идентификатор из одного слова, который используется во всех этих тегах, как показано ниже в `group`.
+По умолчанию этот идентификатор отображается как заголовок раздела документации,
+но можно использовать `@groupname`, чтобы указать более длинный заголовок.
+
+Как правило, необходимо поместить `@groupprio` (и, возможно, `@groupname` и `@groupdesc`) в Scaladoc для самого пакета/трейта/класса/объекта,
+описывая все группы и их порядок. Затем поместить `@group` в Scaladoc для каждого члена, указав, в какой группе он находится.
+
+Члены, у которых нет тега `@group`, будут перечислены в результирующей документации как “Ungrouped”.
+
+- `@group ` - пометить сущность как члена `` группы
+- `@groupname ` - указание необязательного имени для группы. `` отображается как заголовок группы перед её описанием.
+- `@groupdesc ` - добавление необязательного описания для отображения под именем группы. Поддерживает многострочный форматированный текст.
+- `@groupprio ` - управление порядком группы на странице. По умолчанию 0. Несгруппированные элементы имеют неявный приоритет 1000.
+ Используются значения от 0 до 999, чтобы задать положение относительно других групп. Малые значения появятся перед большими значениями.
+
+### Другие теги
+
+- `@author` предоставление информации об авторе для следующего объекта.
+- `@version` версия системы или API, частью которой является этот объект.
+- `@since` похож на `@version`, но определяет систему или API, в котором эта сущность была впервые определена.
+- `@deprecated` помечает объект как устаревший, предоставляя как замену реализации, которую следует использовать,
+ так и версию/дату, когда этот объект устарел.
+- `@syntax ` позволяет изменить парсер для docstring. Синтаксис по умолчанию — markdown,
+ однако можно изменить его с помощью этой директивы. В настоящее время доступны синтаксисы `markdown` или `wiki`.
+ Пример использования: `@syntax wiki`.
+
+### Макросы
+
+- `@define ` позволяет использовать $name в других комментариях Scaladoc в том же исходном файле, который будет заменен на ``.
+
+Если комментарий не предоставляется для объекта на текущем уровне наследования,
+но предоставляется для переопределенного объекта на более высоком уровне иерархии наследования,
+будет использоваться комментарий из суперкласса.
+
+Аналогично, если `@param`, `@tparam`, `@return` и другие теги сущностей опущены, но доступны из суперкласса, будут использоваться из суперкласса.
+
+### Явный
+
+Для явного наследования комментариев используется тег `@inheritdoc`.
+
+### Разметка
+
+Scaladoc предоставляет два анализатора синтаксиса: `markdown` (по умолчанию) или `wikidoc`.
+В Scaladoc по-прежнему можно встраивать теги HTML (как и в Javadoc), но в большинстве случаев это не обязательно,
+поскольку вместо этого может использоваться разметка.
+
+#### Markdown
+
+Markdown использует [вариант commonmark](https://spec.commonmark.org/current/) с двумя пользовательскими расширениями:
+- `wikidoc` ссылки для удобства
+- `wikidoc`кодовые блоки с синтаксисом фигурных скобок
+
+#### Wikidoc
+
+Wikidoc — это синтаксис, используемый для scala2 scaladoc.
+Он поддерживается из-за многих существующих исходников, однако **не** рекомендуется его использование в новых проектах.
+Синтаксис вики можно включить с помощью глобального флага `-comment-syntax wiki` или с помощью `@syntax wiki` директивы в строке документации.
+
+Некоторые из стандартных доступных разметок:
+
+```
+`monospace`
+''italic text''
+'''bold text'''
+__underline__
+^superscript^
+,,subscript,,
+[[entity link]], e.g. [[scala.collection.Seq]]
+[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]]
+```
+
+Для получения дополнительной информации о вики-ссылках см. [эту главу](#связывание-с-api).
+
+Другие примечания по форматированию
+
+- Абзацы начинаются с одной (или нескольких) пустых строк. `*` на полях для комментария допустимо (и должно быть включено),
+ в противном случае строка должна оставаться пустой.
+- Заголовки определяются окружающими символами `=` с большим количеством `=` для обозначения подзаголовков.
+ Например `=Heading=`, `==Sub-Heading==` и т.д.
+- Блоки списка представляют собой последовательность элементов списка с одинаковым стилем и уровнем,
+ без прерываний от других стилей блоков. Неупорядоченные списки можно маркировать с помощью `-`,
+ нумерованные списки можно обозначать с помощью `1.`, `i.`, `I.` или `a.` для различных стилей нумерации.
+ В обоих случаях должно быть дополнительное пространство впереди, а большее пространство создает подуровень.
+
+Разметка для блоков списка выглядит так:
+
+```
+/** Вот неупорядоченный список:
+ *
+ * - Первый элемент
+ * - Второй элемент
+ * - Подпункт ко второму
+ * - Еще один подпункт
+ * - Третий пункт
+ *
+ * Вот упорядоченный список:
+ *
+ * 1. Первый пронумерованный элемент
+ * 1. Второй номер позиции
+ * i. Подпункт ко второму
+ * i. Еще один подпункт
+ * 1. Третий пункт
+ */
+```
+
+### Общие примечания по написанию комментариев к Scaladoc
+
+Краткость - это хорошо! Быстро переходите к сути, у людей ограничено время, которое они могут потратить на вашу документацию,
+используйте его с умом. Опустите ненужные слова. "Prefer возвращает X", а не "этот метод возвращает X",
+и "X, Y и Z", а не "этот метод возвращает X, Y и Z".
+Принцип DRY (_Don’t repeat yourself_) - не повторяйтесь.
+Не дублируйте описание метода в теге `@return` и других формах повторяющихся комментариев.
+
+### Подробнее о написании Scaladoc
+
+Дополнительную информацию о рекомендациях по форматированию и стилю можно найти
+в [руководстве по стилю Scala-lang scaladoc](https://docs.scala-lang.org/style/scaladoc.html).
+
+## Связывание с API
+
+Scaladoc позволяет ссылаться на документацию по API с помощью ссылок в стиле Wiki.
+Связать с `scala.collection.immutable.List` так же просто, как указать `[[scala.collection.immutable.List]]`.
+Для получения дополнительной информации о точном синтаксисе см. [ссылки в документации](/ru/scala3/guides/scaladoc/linking.html#определение-ссылок).
diff --git a/_ru/scala3/guides/scaladoc/index.md b/_ru/scala3/guides/scaladoc/index.md
new file mode 100644
index 0000000000..048272f371
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/index.md
@@ -0,0 +1,13 @@
+---
+layout: multipage-overview
+title: Scaladoc
+partof: scala3-scaladoc
+language: ru
+num: 1
+next-page: docstrings
+---
+
+
+
+Scaladoc — это инструмент для создания API документации ваших проектов Scala 3.
+Он предоставляет функциональность, аналогичную `javadoc`, а также `jekyll` или `docusaurus`.
diff --git a/_ru/scala3/guides/scaladoc/linking.md b/_ru/scala3/guides/scaladoc/linking.md
new file mode 100644
index 0000000000..fd0670ba65
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/linking.md
@@ -0,0 +1,94 @@
+---
+layout: multipage-overview
+title: Ссылки в документации
+partof: scala3-scaladoc
+language: ru
+num: 3
+previous-page: docstrings
+next-page: static-site
+---
+
+Основная функция Scaladoc — создание API документации из комментариев к коду.
+
+По умолчанию комментарии к коду понимаются как Markdown, хотя мы также поддерживаем старый Scaladoc синтаксис
+[Wiki](https://docs.scala-lang.org/style/scaladoc.html).
+
+## Синтаксис
+
+### Определение ссылок
+
+Наш синтаксис определения ссылки очень близок к синтаксису 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` помогает сделать ссылки на прилагаемый пакет короче
+ и немного более устойчивым к рефакторингу имен.
+1. `this` может использоваться в качестве префикса для ссылки на прилагаемый классоподобный пример:
+ ```
+ class C {
+ def foo = "foo"
+ /** This is not [[this.foo]], this is bar. */
+ def bar = "bar"
+ }
+ ```
+ Использование здесь ключевого слова помогает сделать ссылки более привычными,
+ а также помогает ссылкам "пережить" изменения имени класса.
+1. Обратные кавычки могут использоваться для экранирования идентификаторов.
+ Пример:
+ ```
+ 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 даже не сохраняет никаких символов.
diff --git a/_ru/scala3/guides/scaladoc/search-engine.md b/_ru/scala3/guides/scaladoc/search-engine.md
new file mode 100644
index 0000000000..9ef88e0630
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/search-engine.md
@@ -0,0 +1,102 @@
+---
+layout: multipage-overview
+title: Поиск по типу
+partof: scala3-scaladoc
+language: ru
+num: 7
+previous-page: site-versioning
+next-page: snippet-compiler
+---
+
+Поиск функций по их символическим именам может занять много времени.
+Именно поэтому новый scaladoc позволяет искать методы и поля по их типам.
+
+Рассмотрим следующее определение метода расширения:
+```
+extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ...
+```
+Вместо поиска `span` также можно искать по `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`.
+
+Чтобы использовать эту функцию, введите сигнатуру искомого элемента в строке поиска scaladoc.
+Вот как это работает:
+
+
+
+Эта функция предоставляется поисковой системой [Inkuire](https://github.com/VirtusLab/Inkuire), которая работает для Scala 3 и Kotlin.
+Чтобы быть в курсе развития этой функции, следите за репозиторием [Inkuire](https://github.com/VirtusLab/Inkuire).
+
+## Примеры запросов
+
+Некоторые примеры запросов с предполагаемыми результатами:
+- `List[Int] => (Int => Long) => List[Long]` -> `map`
+- `Seq[A] => (A => B) => Seq[B]` -> `map`
+- `(A, B) => A` -> `_1`
+- `Set[Long] => Long => Boolean` -> `contains`
+- `Int => Long => Int` -> `const`
+- `String => Int => Char` -> `apply`
+- `(Int & Float) => (String | Double)` -> `toDouble`, `toString`
+- `F[A] => Int` -> `length`
+
+## Синтаксис запроса
+
+Для того чтобы запрос панели поиска scaladoc выполнялся с использованием Inkuire вместо поисковой системы по умолчанию,
+запрос должен содержать последовательность символов `=>`.
+
+Принятый ввод аналогичен сигнатуре каррированной функции в Scala 3. С некоторыми отличиями:
+- AndTypes, OrTypes и Functions должны быть заключены в круглые скобки, например, `(Int & Any) => String`
+- поля и методы без параметров можно найти, указав перед их типом `=>`, например, `=> Int`
+- Можно использовать подстановочный знак `_`, чтобы указать, что необходимо сопоставить любой тип в данном месте,
+ например, `Long => Double => _`
+- Типы в виде одной буквы, например `A`, или буквы с цифрой `X1`, автоматически считаются переменными типа.
+- Другие переменные типа могут быть объявлены так же, как и в полиморфных функциях,
+ например `[AVariable, AlsoAVariable] => AVariable => AlsoAVariable => AVariable`
+
+### Работа с псевдонимами типов и приемниками методов
+
+Когда дело доходит до того, как код сопоставляется с записями InkuireDb, есть некоторые преобразования,
+чтобы сделать движок более самостоятельным (хотя и открытым для предложений и изменений).
+Во-первых, получатель (не владелец модуля) функции может рассматриваться как первый аргумент.
+Также применяется автоматическое каррирование, чтобы результаты не зависели от списков аргументов.
+При поиске совпадений `val` и `def` не различаются.
+
+Итак, по запросу `Num => Int => Int => Int` должны быть найдены следующие объявления:
+```
+class Num():
+ def a(i: Int, j: Int): Int
+ def b(i: Int)(j: Int): Int
+ def c(i: Int): (Int => Int)
+ val d: Int => Int => Int
+ val e: Int => Int => Int
+ val f: (Int, Int) => Int
+end Num
+
+def g(i: Num, j: Int, k: Int): Int
+extension (i: Num) def h(j: Int, k: Int): Int
+def i(i: Num, j: Int)(k: Int): Int
+extension (i: Num) def j(j: Int)(k: Int): Int
+...
+```
+
+Когда дело доходит до псевдонимов типов, они дешугаризуются как в объявлении, так и в подписи запроса.
+Это означает, что для объявлений:
+```
+type Name = String
+
+def fromName(name: Name): String
+def fromString(str: String): Name
+```
+оба метода `fromName` и `fromString`, должны быть найдены по запросам `Name => Name`, `String => String`, `Name => String` и `String => Name`.
+
+## Как это работает
+
+Inkuire работает как рабочий JavaScript в браузере благодаря мощи [ScalaJS](https://www.scala-js.org/).
+
+Чтобы включить Inkuire при запуске scaladoc, добавьте флаг `-Ygenerate-inkuire`.
+При добавлении этого флага создаются два файла:
+- `inkuire-db.json` - это файл, содержащий все доступные для поиска объявления из текущего документированного проекта в формате,
+ читаемом поисковой системой Inkuire.
+- `inkuire-config.json` - этот файл содержит расположение файлов базы данных,
+ которые должны быть доступны для поиска в документации текущего проекта.
+ По умолчанию он будет сгенерирован с расположением локального файла базы данных,
+ а также с подразумеваемыми по умолчанию расположениями файлов базы данных во внешних сопоставлениях
+ [`-external-mappings`](/ru/scala3/guides/scaladoc/settings.html#-external-mappings).
diff --git a/_ru/scala3/guides/scaladoc/settings.md b/_ru/scala3/guides/scaladoc/settings.md
new file mode 100644
index 0000000000..b7ec438ac8
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/settings.md
@@ -0,0 +1,197 @@
+---
+layout: multipage-overview
+title: Настройки
+partof: scala3-scaladoc
+language: ru
+num: 9
+previous-page: snippet-compiler
+---
+
+В этой главе перечислены параметры конфигурации, которые можно использовать при вызове scaladoc.
+Некоторую информацию, показанную здесь, можно получить, вызвав scaladoc с флагом `-help`.
+
+## Изменения scaladoc по сравнению со Scala 2
+
+Scaladoc был переписан с нуля, и некоторые функции оказались бесполезными в новом контексте.
+Текущее состояние совместимости со старыми флагами scaladoc можно увидеть [здесь](https://github.com/lampepfl/dotty/issues/11907).
+
+## Указание настроек
+
+Настройки scaladoc можно указывать в качестве аргументов командной строки,
+например, `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`.
+При вызове из sbt, обновите значение `Compile / doc / scalacOptions` и `Compile / doc / target` соответственно, например
+
+```
+Compile / doc / target := file("output"),
+Compile / doc / scalacOptions ++= Seq("-project", "my-project"),
+```
+
+## Обзор всех доступных настроек
+
+##### -project
+Название проекта. Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-title`
+
+##### -project-version
+Текущая версия проекта, которая отображается в верхнем левом углу.
+Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-version`
+
+##### -project-logo
+Логотип проекта, который появляется в верхнем левом углу.
+Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-logo`
+
+##### -project-footer
+Строковое сообщение, которое отображается в разделе нижнего колонтитула.
+Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-footer`
+
+##### -comment-syntax
+Язык стилей, используемый для разбора комментариев.
+В настоящее время поддерживается два синтаксиса: `markdown` или `wiki`.
+Если настройка отсутствует, по умолчанию - `markdown`.
+
+##### -revision
+Редакция (ветвь или ссылка), используемая для создания проекта.
+Полезно с исходными ссылками, чтобы они не всегда указывали на последний `main`, который может быть изменен.
+
+##### -source-links
+Ссылки на источники обеспечивают сопоставление между файлом в документации и репозиторием кода.
+
+Примеры исходных ссылок:
+`-source-links:docs=github://lampepfl/dotty/master#docs`
+
+Принимаемые форматы:
+
+`=`
+
+где `` является одним из следующих:
+ - `github:///[/revision][#subpath]`
+ будет соответствовать https://github.com/$organization/$repository/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber],
+ если редакция не указана, тогда требуется указать редакцию в качестве аргумента для Scaladoc
+ - `gitlab:///`
+ будет соответствовать https://gitlab.com/$organization/$repository/-/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber],
+ если редакция не указана, тогда требуется, чтобы редакция была указана как аргумент в Scaladoc
+ - ``
+
+`` — это формат параметра `doc-source-url` из старого scaladoc.
+ПРИМЕЧАНИЕ. Поддерживаются только шаблоны `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`, `€{FILE_PATH}` и `€{FILE_LINE}`.
+
+Шаблон может быть определен только подмножеством источников, определенных префиксом пути, представленным ``.
+В этом случае пути, используемые в шаблонах, будут относительными относительно ``.
+
+
+##### -external-mappings
+
+Сопоставление регулярных выражений, соответствующих записям пути к классам, и внешней документации.
+
+Пример внешнего сопоставления:
+`-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/`
+
+Отображение имеет вид `::[scaladoc3|scaladoc|javadoc]::`.
+Можно указать несколько сопоставлений, разделенных запятыми, как показано в примере.
+
+##### -social-links
+
+Ссылки на социальные сети. Например:
+
+`-social-links:github::https://github.com/lampepfl/dotty,discord::https://discord.com/invite/scala,twitter::https://twitter.com/scala_lang`
+
+Допустимые значения имеют вид: `[github|twitter|gitter|discord]::link`.
+Scaladoc также поддерживает `custom::link::white_icon_name::black_icon_name`.
+В этом случае иконки должны находиться в каталоге `images/`.
+
+##### -skip-by-id
+
+Идентификаторы пакетов или классов верхнего уровня, которые следует пропускать при создании документации.
+
+##### -skip-by-regex
+
+Регулярные выражения, соответствующие полным именам пакетов или классов верхнего уровня,
+которые следует пропускать при создании документации.
+
+##### -doc-root-content
+
+Файл, из которого следует импортировать документацию корневого пакета.
+
+##### -author
+
+Добавление авторов в строку документации `@author Name Surname` по умолчанию не будет включено в сгенерированную html-документацию.
+Если необходимо явно пометить классы авторами, scaladoc запускается с данным флагом.
+
+##### -groups
+
+Группировка похожих функций вместе (на основе аннотации `@group`)
+
+##### -private
+
+Показать все типы и члены. Если параметр не указан, показывать только `public` и `protected` типы и члены.
+
+##### -doc-canonical-base-url
+
+Базовый URL-адрес для использования в качестве префикса и добавления `canonical` URL-адресов на все страницы.
+Канонический URL-адрес может использоваться поисковыми системами для выбора URL-адреса,
+который вы хотите, чтобы люди видели в результатах поиска.
+Если не установлено, канонические URL-адреса не генерируются.
+
+##### -siteroot
+
+Каталог, содержащий статические файлы, из которых создается документация. Каталог по умолчанию - `./docs`
+
+##### -no-link-warnings
+
+Подавить предупреждения для двусмысленных или невалидных ссылок.
+Не влияет на предупреждения о некорректных ссылках ресурсов и т. д.
+
+##### -versions-dictionary-url
+
+URL-адрес, указывающий на документ JSON, содержащий словарь: `version label -> documentation location`.
+Файл JSON имеет единственное свойство `versions`, которое содержит словарь,
+связывающий метки определенных версий документации с URL-адресами, указывающими на их `index.html`.
+Полезно для библиотек, которые поддерживают разные версии документации.
+
+Пример JSON-файла:
+```
+{
+ "versions": {
+ "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
+ "Nightly": "https://dotty.epfl.ch/docs/index.html"
+ }
+}
+```
+
+##### -snippet-compiler
+
+Аргументы компилятора фрагментов, позволяющие настроить проверку типа сниппета.
+
+Этот параметр принимает список аргументов в формате:
+`args := arg{,args} arg := [path=]flag`
+, где `path` - префикс пути к исходным файлам, в которых находятся сниппеты,
+и `flag` - режим проверки типов.
+
+Если `path` отсутствует, аргумент будет использоваться по умолчанию для всех несопоставленных путей.
+
+Доступные флаги:
+- `compile` — включает проверку фрагментов.
+- `nocompile` — отключает проверку сниппетов.
+- `fail` — включает проверку фрагмента, утверждает, что сниппет не компилируется.
+
+Флаг `fail` удобен для фрагментов, которые показывают,
+что какое-то действие в конечном итоге завершится ошибкой во время компиляции.
+
+Пример использования:
+
+`-snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile`
+
+Что значит:
+
+- все фрагменты в файлах в каталоге `my/path/nc` вообще не должны рассматриваться снипеттом
+- все фрагменты в файлах в каталоге `my/path/f` не должны компилироваться во время компиляции
+- все остальные фрагменты должны компилироваться успешно
+
+##### -Ysnippet-compiler-debug
+
+Установка этого параметра заставляет компилятор фрагментов печатать сниппет по мере его компиляции (после упаковки).
+
+##### -Ydocument-synthetic-types
+
+Включение в документацию страниц с документацией по встроенным типам (например, `Any`, `Nothing`).
+Этот параметр полезен только для stdlib, поскольку scaladoc для Scala 3 использует файлы TASTy.
+Все остальные пользователи не должны касаться этой настройки.
diff --git a/_ru/scala3/guides/scaladoc/site-versioning.md b/_ru/scala3/guides/scaladoc/site-versioning.md
new file mode 100644
index 0000000000..fac5266a7c
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/site-versioning.md
@@ -0,0 +1,51 @@
+---
+layout: multipage-overview
+title: Версионирование сайта
+partof: scala3-scaladoc
+language: ru
+num: 6
+previous-page: blog
+next-page: search-engine
+---
+
+Scaladoc предоставляет удобный способ переключения между различными версиями документации.
+Эта функция полезна, когда желательно оставить старые версии документации пользователям,
+которые ещё не перешли на новую версию библиотеки.
+
+### Как это настроить
+
+Эта функция была разработана для легкой масштабируемости без необходимости повторного создания всех scaladocs
+после добавления новой версии. Для этого вводится новая настройка: `-versions-dictionary-url`.
+Его аргумент должен быть URL-адресом документа JSON, содержащего информацию о расположении конкретных версий.
+Файл JSON должен содержать свойство `versions` со словарём,
+связывающий метки определенных версий документации с URL-адресами, указывающими на их `index.html`.
+
+Пример JSON-файла:
+```
+{
+ "versions": {
+ "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
+ "Nightly": "https://dotty.epfl.ch/docs/index.html"
+ }
+}
+```
+
+Такие документы необходимо указывать для каждой из версий, однако позже это дает больше гибкости.
+Если необходимо добавить версию документов API рядом с предыдущими 5 версиями, которые уже опубликованы,
+нужно только загрузить новые документы на веб-сервер и добавить новую запись в файл JSON.
+Все версии сайта теперь узнают о новой версии.
+
+Важно отметить, что существует только один файл JSON, чтобы избежать избыточности,
+и каждый scaladoc должен заранее настроить свой URL-адрес, например, в sbt:
+
+```
+doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/versions.json")
+```
+
+
+### Как это выглядит с точки зрения пользователя
+
+Предоставление файла JSON через `-versions-dictionary-url` позволяет scaladoc связывать версии.
+Также удобно иметь возможность изменить метку ревизии в выпадающем меню. Все изменится автоматически.
+
+
diff --git a/_ru/scala3/guides/scaladoc/snippet-compiler.md b/_ru/scala3/guides/scaladoc/snippet-compiler.md
new file mode 100644
index 0000000000..adb2c0932c
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/snippet-compiler.md
@@ -0,0 +1,261 @@
+---
+layout: multipage-overview
+title: Проверка фрагмента
+partof: scala3-scaladoc
+language: ru
+num: 8
+previous-page: search-engine
+next-page: settings
+---
+
+Основная функциональность документации — помочь пользователям понять и правильно использовать проект.
+Иногда часть проекта нуждается в нескольких словах, чтобы показать ее использование,
+но бывают моменты, когда описания недостаточно, и нет ничего лучше, чем подробный пример.
+
+Удобный способ предоставления примеров в документации — создание фрагментов кода,
+представляющих использование заданной функциональности. Проблема фрагментов кода в том,
+что одновременно с разработкой проекта их нужно обновлять.
+Иногда изменения в одной части проекта могут нарушить работу примеров в других частях.
+Количество фрагментов и количество времени, прошедшего с момента их написания, не позволяет запомнить каждое место,
+где нужно их исправить. Через какое-то время наступает понимание, что документация — полный бардак
+и нужно пройтись по всем примерам и переписать их.
+
+Многие проекты Scala 2 используют markdown документацию с проверкой типов с помощью [tut](https://tpolecat.github.io/tut/)
+или [mdoc](https://scalameta.org/mdoc/). Почти все хотя бы слышали об этих инструментах.
+Поскольку они оказались очень полезными и сообщество Scala их успешно приняло,
+планируется включить функции tut и mdoc в компилятор, чтобы он был готов к включению в Scaladoc.
+
+
+
+## Начало работы
+
+По умолчанию проверка фрагментов отключена.
+Её можно включить, добавив в Scaladoc следующий аргумент:
+
+`-snippet-compiler:compile`
+
+Например, в sbt конфигурация выглядит так:
+
+```scala
+Compile / doc / scalacOptions ++= Seq("-snippet-compiler:compile")
+```
+
+Эта опция включает компилятор фрагментов для всех scala фрагментов в проектной документации и распознает все фрагменты внутри ``` блоков scala.
+В настоящее время проверка фрагментов работает как в строках документации, написанных в Markdown, так и на статических сайтах.
+
+
+Для нового проекта этой конфигурации должно хватить.
+Однако, если вы переносите существующий проект, можно отключить компиляцию для некоторых фрагментов,
+которые в настоящее время не могут быть обновлены.
+
+Для этого добавьте `nocompile` флаг прямо в scala фрагмент:
+
+````
+```scala sc:nocompile
+// under the hood `map` is transformed into
+List(1).map( _ + 1)()
+```
+````
+
+Однако иногда сбой компиляции является преднамеренным поведением, например, для демонстрации ошибки.
+В этом случае выставляется флаг `fail`, который представляет одну из функций: [Assert compilation errors](#assert-compilation-errors).
+
+````
+```scala sc:fail
+List(1,2,3).toMap
+```
+````
+
+Более подробное объяснение и более сложные настройки, такие как настройки флагов на основе пути,
+см. в разделе ["Расширенная конфигурация"](#расширенная-конфигурация).
+
+## Обзор функций
+
+### Assert compilation errors
+
+Scala — это язык программирования со статической типизацией.
+Иногда в документации должны упоминаться случаи, когда код не должен компилироваться,
+или авторы хотят предоставить способы восстановления после определенных ошибок компиляции.
+
+Например, этот код:
+
+```scala
+List(1,2,3).toMap
+```
+
+приводит к результату:
+
+```nohighlight
+
+At 18:21:
+ List(1,2,3).toMap
+Error: Cannot prove that Int <:< (K, V)
+
+where: K is a type variable with constraint
+ V is a type variable with constraint
+.
+```
+
+Примеры, представляющие код, который дает сбой во время компиляции, могут быть очень важными.
+Например, можно показать, как библиотека защищена от неправильного кода.
+Другой вариант использования — представить распространенные ошибки и способы их решения.
+Принимая во внимание эти варианты использования, предоставляется функция проверки того, компилируются ли отмеченные фрагменты кода.
+
+Для фрагментов кода, которые намеренно не компилируются, например следующего, добавьте флаг `fail` во фрагмент кода:
+
+````
+```scala sc:fail
+List(1,2,3).toMap
+```
+````
+Проверка фрагмента проходит успешно и показывает ожидаемые ошибки компиляции в документации.
+
+
+Для фрагмента, который компилируется без ошибок:
+````
+```scala sc:fail
+List((1,2), (2,3)).toMap
+```
+````
+результирующий вывод выглядит следующим образом:
+```nohighlight
+
+In static site (./docs/docs/index.md):
+Error: Snippet should not compile but compiled succesfully
+```
+
+
+### Контекст
+
+В Scaladoc внедрён механизм переноса, предоставляющий контекст для каждого фрагмента.
+Эта предварительная обработка выполняется автоматически для всех фрагментов в строках документации.
+
+Например, предположим, что необходимо задокументировать метод `slice` в файле `collection.List` для того,
+чтобы объяснить, как он работает, сравнив его с комбинацией методов `drop` и `take`, используя такой фрагмент кода:
+```scala
+slice(2, 5) == drop(2).take(3)
+```
+Показ этого примера — одна из первых вещей, которые приходят на ум, но он не скомпилируется без функции контекста.
+
+Помимо основной цели, это уменьшает шаблон фрагмента, потому что не нужно импортировать элементы одного и того же пакета
+и создавать экземпляры документированного класса.
+
+Фрагмент кода после предварительной обработки выглядит так:
+```scala
+package scala.collection
+trait Snippet[A] { self: List[A] =>
+ slice(2,5) == drop(2).take(3)
+}
+```
+
+### Скрытие кода
+
+Несмотря на наличие контекстной функции, описанной выше, иногда автору необходимо предоставить больше элементов
+для области действия. Однако, с одной стороны, большой блок импортов и инициализаций необходимых классов
+может привести к потере читабельности. Но с другой стороны, хотелось бы иметь возможность видеть весь код.
+Для второго случая введен специальный синтаксис для фрагментов,
+который скрывает определенные фрагменты `import` кода — операторы, например, — но также позволяет
+расширить этот код в документации одним щелчком мыши.
+
+Пример:
+
+```scala
+//{
+import scala.collection.immutable.List
+//}
+val intList: List[Int] = List(1, 2, 3)
+```
+
+
+
+### Включенные фрагменты
+
+При написании фрагментов кода часто требуется механизм повторного использования кода из одного фрагмента в другом.
+Например, взгляните на следующий фрагмент документации:
+
+
+Чтобы успешно скомпилировать последний фрагмент, нужно иметь ранее объявленные определения в области видимости.
+Для этого сценария — и, возможно, для многих других — добавлена новая функция: включение фрагмента.
+Она позволяет повторно использовать код из одного фрагмента в другом, что снижает избыточность и повышает удобство сопровождения.
+
+Чтобы настроить это, добавьте аргумент `sc-name` к фрагменту, который необходимо включить в более поздний блок кода:
+```` ```scala sc-name: ````
+
+, где `snippet-name` должен быть уникальным в пределах файла и не может содержать пробелы и запятые.
+
+Затем в более позднем блоке кода в документации используйте аргумент `sc-compile-with` в scala фрагменте,
+который должен “включать” предыдущий блок кода:
+```` ```scala sc-compile-with:(,)+ ````
+
+, где `snippet-name` - имя фрагмента, который должен быть включен.
+
+После настройки этой функции в примере код выглядит так:
+
+
+и вывод выглядит так:
+
+
+Можно указать более одного включения. Обратите внимание, что порядок, в котором они указаны, определяет порядок включения.
+
+**Замечание**: можно включать только фрагменты, определенные над целевым фрагментом.
+
+## Расширенная конфигурация
+
+Часто включение проверки фрагментов для _всех_ фрагментов не является желаемым уровнем контроля,
+поскольку варианты использования могут быть более сложными. Для таких ситуаций подготовлен инструмент,
+чтобы пользователи могли настроить его под свои нужды.
+
+### Доступные флаги
+
+Чтобы обеспечить больший контроль, компилятор фрагмента предоставляет три флага, которые позволяют изменить его поведение:
+- `compile` - включает проверку фрагментов
+- `nocompile` - отключает проверку фрагментов
+- `fail` - включает проверку фрагментов с подтверждением ошибки компиляции
+
+### Настройки на основе пути
+
+Для большей гибкости вместо установки одного флага для управления всеми фрагментами кода в проекте
+его можно установить только для определенного пути, добавив префикс `=` перед флагом. Например:
+
+`-snippet-compiler:docs=compile` - устанавливает флаг `compile` для фрагментов в `docs`.
+
+Если `docs` - это каталог, флаг устанавливается для всех файлов внутри `docs`.
+
+Кроме того, `-snippet-compiler` может управляться более чем одним параметром, при этом параметры разделяются запятыми.
+Например:
+```
+-snippet-compiler:docs=compile,library/src=compile,library/src/scala/quoted=nocompile,library/src/scala/compiletime=fail
+```
+Флаги выбираются по самому длинному совпадению префикса, поэтому можно определить общую настройку,
+а затем изменить это поведение по умолчанию для более конкретных путей.
+```
+-snippet-compiler:compile,library/src/scala/quoted=nocompile,library/src/scala/compiletime=fail
+```
+Флаг без префикса пути, такой как флаг `compile` в этом примере, считается значением по умолчанию.
+
+### Переопределение прямо во фрагменте
+
+Аргументы CLI — хороший механизм для установки флагов для определенных файлов.
+Однако этот подход нельзя использовать для настройки определенных фрагментов.
+Допустим, необходимо написать один фрагмент кода, который должен потерпеть неудачу,
+и другие фрагменты, которые должны скомпилироваться.
+Эти аргументы находятся в информационной части блока кода:
+
+````
+```scala
+// snippet
+```
+````
+
+Например, чтобы настроить проверку для определенного фрагмента, добавьте следующий аргумент в его информационную часть фрагмента,
+где `flag` - один из доступных флагов, перечисленных выше (например, `compile`, `nocompile` или `fail`):
+
+`sc:`
+
+В качестве конкретного примера этот код показывает, как использовать флаг `fail` в отдельном фрагменте:
+
+````
+```scala sc:fail
+val itShouldFail: Int = List(1.1, 2, 3).head
+```
+````
diff --git a/_ru/scala3/guides/scaladoc/static-site.md b/_ru/scala3/guides/scaladoc/static-site.md
new file mode 100644
index 0000000000..10486b8c20
--- /dev/null
+++ b/_ru/scala3/guides/scaladoc/static-site.md
@@ -0,0 +1,243 @@
+---
+layout: multipage-overview
+title: Статическая документация
+partof: scala3-scaladoc
+language: ru
+num: 4
+previous-page: linking
+next-page: blog
+---
+
+Scaladoc умеет генерировать статические сайты, известные по [Jekyll](http://jekyllrb.com/) или [Docusaurus](https://docusaurus.io/).
+Наличие комбинированного инструмента позволяет обеспечить взаимодействие между статической документацией
+и API, что позволяет им естественным образом сочетаться.
+
+Создать сайт так же просто, как и в Jekyll. Корень сайта содержит макет сайта,
+и все файлы, размещенные там, будут либо считаться статическими, либо обрабатываться для расширения шаблона.
+
+Файлы, которые рассматриваются для расширения шаблона, должны заканчиваться на `*.{html,md}`
+и в дальнейшем будут называться "файлами шаблонов" или "шаблонами".
+
+Простой сайт "Hello World" может выглядеть примерно так:
+
+```
+.
+└── /
+ └── _docs/
+ ├── index.html
+ └── getting-started.html
+```
+
+Что даст сайт со следующими файлами в сгенерированной документации:
+
+```
+index.html
+getting-started.html
+```
+
+Scaladoc может преобразовывать как файлы, так и каталоги (чтобы организовать документацию в древовидную структуру).
+По умолчанию каталоги имеют заголовок, основанный на имени файла, с пустым содержимым.
+Можно предоставить индексные страницы для каждого раздела, создав `index.html` или `index.md` (но не одновременно) в выделенном каталоге.
+
+Имейте в виду, что для локального просмотра вашего сайта со всеми его функциями, такими как поиск или фрагменты,
+требуется локальный сервер. Например, если ваш выходной каталог - `output`,
+вы можете использовать python сервер для просмотра всего, выполнив следующие действия и открыв `localhost:8080`:
+
+```sh
+cd output
+python3 -m http.server 8080
+```
+
+## Характеристики
+
+Scaladoc использует механизм шаблонов [Liquid](https://shopify.github.io/liquid/)
+и предоставляет несколько настраиваемых фильтров и тегов, характерных для документации Scala.
+
+В Scaladoc все шаблоны могут содержать вступительную часть YAML.
+Передняя часть анализируется и помещается в переменную `page`, доступную в шаблонах через Liquid.
+
+Пример вступительной статьи:
+
+```
+---
+title: My custom title
+---
+```
+
+Scaladoc использует некоторые предопределенные свойства для управления аспектами страницы.
+
+Предустановленные свойства:
+
+- **title** - обеспечивает заголовок страницы, который будет использоваться в навигации и метаданных HTML.
+- **extraCss** - дополнительные файлы `.css`, которые будут включены в эту страницу.
+ Пути должны указываться относительно корня документации. **Этот параметр не экспортируется в механизм шаблонов.**
+- **extraJs** - дополнительные файлы `.js`, которые будут включены в эту страницу.
+ Пути должны указываться относительно корня документации. **Этот параметр не экспортируется в механизм шаблонов.**
+- **hasFrame** - если установлено значение `false`, страница не будет включать макет по умолчанию (навигацию, breadcrumbs и т.д.),
+ а только токен-оболочку HTML для предоставления метаданных и ресурсов (файлы js и css). **Этот параметр не экспортируется в механизм шаблонов.**
+- **layout** - предопределенный макет для использования, см. ниже. **Этот параметр не экспортируется в механизм шаблонов.**
+
+## Использование существующих шаблонов и макетов
+
+Чтобы выполнить расширение шаблона, Dottydoc просматривает поле `layout` во вступительной части.
+Вот простой пример системы шаблонов в действии `index.html`:
+
+```html
+---
+layout: main
+---
+
+Hello world!
+```
+
+С таким простым основным шаблоном, как этот:
+
+{% raw %}
+```html
+
+
+ Hello, world!
+
+
+ {{ content }}
+
+
+```
+
+`{{ content }}` будет заменен на `Hello world!
` в файле `index.html`.
+{% endraw %}
+
+Макеты должны быть размещены в каталоге `_layouts` в корне сайта:
+
+```
+├── _layouts
+│ └── main.html
+└── _docs
+ ├── getting-started.md
+ └── index.html
+```
+
+## Ресурсы
+
+Чтобы рендерить ассеты вместе со статическим сайтом, их нужно поместить в директорию `_assets` в корне сайта:
+```
+├── _assets
+│ └── images
+│ └── myimage.png
+└── _docs
+ └── getting-started.md
+```
+Чтобы сослаться на ресурс на странице, необходимо создать ссылку относительно каталога `_assets`.
+
+```
+Take a look at the following image: [My image](images/myimage.png)
+```
+
+## Боковая панель
+
+По умолчанию Scaladoc отображает структуру каталогов из каталога `_docs` на визуализируемом сайте.
+Существует также возможность переопределить его, предоставив файл `sidebar.yml` в корневом каталоге сайта.
+Конфигурационный файл YAML описывает структуру отображаемого статического сайта и оглавление:
+
+```yaml
+index: index.html
+subsection:
+ - title: Usage
+ index: usage/index.html
+ directory: usage
+ subsection:
+ - title: Dottydoc
+ page: usage/dottydoc.html
+ hidden: false
+ - title: sbt-projects
+ page: usage/sbt-projects.html
+ hidden: false
+```
+Корневой элемент должен быть `subsection`.
+Вложенные подразделы приведут к древовидной структуре навигации.
+
+Свойства `subsection`:
+ - `title` - Необязательная строка - заголовок подраздела по умолчанию.
+ Вступительные заголовки имеют более высокий приоритет.
+ - `index` - Необязательная строка - Путь к индексной странице подраздела. Путь указан относительно каталога `_docs`.
+ - `directory` - Необязательная строка - Имя каталога, в котором будет находиться подраздел сгенерированного сайта.
+ По умолчанию именем каталога является имя подраздела, преобразованное в kebab case.
+ - `subsection` - Массив `subsection` или `page`.
+
+Либо `index`, либо `subsection` должны быть определены. Подраздел, определенный с `index` и без `subsection`,
+будет содержать страницы и каталоги, загружаемые рекурсивно из каталога индексной страницы.
+
+Свойства `page`:
+ - `title` - Необязательная строка - заголовок страницы по умолчанию. Вступительные заголовки имеют более высокий приоритет.
+ - `page` - Строка - Путь к странице относительно каталога `_docs`.
+ - `hidden` - Необязательное логическое значение. Флаг, указывающий, должна ли страница отображаться на боковой панели навигации.
+ По умолчанию установлено значение `false`.
+
+**Заметка**: Все пути в файле конфигурации YAML относятся к `/_docs`.
+
+## Иерархия title
+
+Если заголовок указан несколько раз, приоритет будет следующим (от высшего к низшему приоритету):
+
+#### Страница
+
+1. `title` из `front-matter` файла markdown/html
+2. `title` свойство из `sidebar.yml`
+3. имя файла
+
+#### Подраздел
+
+1. `title` из `front-matter` индексного файла markdown/html
+2. `title` свойство из `sidebar.yml`
+3. имя файла
+
+Обратите внимание, что если пропустить `index` файл в древовидной структуре или не указать `title` во вступительной части,
+ему будет присвоено общее имя `index`. То же самое относится к использованию `sidebar.yml`,
+но не указанию ни `title`, ни `index`, а только подраздела. Снова появится общее имя `index`.
+
+## Блог
+Функция блога описана в [отдельном документе](/ru/scala3/guides/scaladoc/blog.html).
+
+## Расширенная конфигурация
+### Полная структура корня сайта
+```
+.
+└── /
+ ├── _layouts/
+ │ └── ...
+ ├── _docs/
+ │ └── ...
+ ├── _blog/
+ │ ├── index.md
+ │ └── _posts/
+ │ └── ...
+ └── _assets/
+ ├── js/
+ │ └── ...
+ ├── img/
+ │ └── ...
+ └── ...
+```
+В результате получается статический сайт, содержащий документы, а также блог.
+Он также содержит пользовательские макеты и ассеты.
+Структура визуализируемой документации может быть основана на файловой системе, но также может быть переопределена конфигурацией YAML.
+
+### Структура каталогов сопоставления
+
+Используя файл конфигурации YAML, можно определить, как структура исходного каталога должна быть преобразована в структуру выходного каталога.
+
+Взглянем на следующее определение подраздела:
+```yaml
+- title: Some other subsection
+ index: abc/index.html
+ directory: custom-directory
+ subsection:
+ - page: abc2/page1.md
+ - page: foo/page2.md
+```
+В этом подразделе показана возможность конфигурации YAML отображать структуру каталогов.
+Несмотря на то, что индексная страница и все определенные дочерние элементы находятся в разных каталогах,
+они будут рендериться в `custom-directory`.
+Исходная страница `abc/index.html` будет генерировать страницу `custom-directory/index.html`,
+исходная страница `abc2/page1.md` - `custom-directory/page1.html`,
+а исходная страница `foo/page2.md` - `custom-directory/page2.html`.
diff --git a/_ru/scala3/new-in-scala3.md b/_ru/scala3/new-in-scala3.md
new file mode 100644
index 0000000000..d4d4ce0773
--- /dev/null
+++ b/_ru/scala3/new-in-scala3.md
@@ -0,0 +1,184 @@
+---
+layout: singlepage-overview
+title: Новое в Scala 3
+partof: scala3-scaladoc
+scala3: true
+language: ru
+---
+
+Захватывающая новая версия Scala 3 содержит множество новых функций и улучшений.
+Здесь мы представляем вам краткий обзор наиболее важных изменений.
+Если вы хотите копнуть глубже, то в вашем распоряжении несколько ссылок:
+
+- [Книга Scala 3]({% link _overviews/scala3-book/introduction.md %}) предназначена для разработчиков, только знакомящихся с языком Scala.
+- [Обзор синтаксиса][syntax-summary] содержит формальное описание нового синтаксиса.
+- [Справочник по языку][reference] дает подробное описание изменений Scala 3 по сравнению со Scala 2.
+- [Руководство по миграции][migration] содержит всю информацию, необходимую для перехода со Scala 2 на Scala 3.
+- [Scala 3 Contributing Guide][contribution] более подробно рассказывает о компиляторе, включая руководство по исправлению проблем.
+
+## Что нового Scala 3
+Scala 3 — это полная переработка языка Scala.
+По сути, многие аспекты системы типов были изменены, чтобы сделать их более последовательными.
+Хотя эта версия также приносит интересные новые функции (например, типы объединения),
+в первую очередь это означает, что система типов становится (даже) малозаметнее на вашем пути,
+и, например, [вывод типов][type-inference] с перегрузкой значительно улучшаются.
+
+### Новое и яркое: синтаксис
+Помимо многих (незначительных) чисток, синтаксис Scala 3 предлагает следующие улучшения:
+
+- Новый "тихий" синтаксис для структур управления, таких как `if`, `while` и `for` ([новый синтаксис управления][syntax-control])
+- Ключевое слово `new` теперь является необязательным (_например_ [для создания экземпляров][creator])
+- [Опциональные фигурные скобки][syntax-indentation] поддерживающие стиль программирования, не отвлекающий внимание и чувствительный к отступам
+- Изменение [подстановочных знаков типа][syntax-wildcard] с `_` на `?`.
+- Имплициты (и их синтаксис) были [значительно переработаны][implicits].
+
+### Последовательное: контекстуальные абстракции
+Одной из основных концепций Scala было (и до некоторой степени до сих пор является)
+предоставление пользователям небольшого набора мощных функций,
+которые можно комбинировать для достижения большей (а иногда даже непредусмотренной) выразительности.
+Например, функциональность _имплицитов_ использовалась для моделирования контекстной абстракции,
+для выражения вычислений на уровне типов, моделирования классов типов, выполнения неявных преобразований,
+кодирования методов расширения и многого другого.
+Извлекая уроки из этих вариантов использования, Scala 3 использует несколько иной подход
+и фокусируется на **намерении**, а не на **механизме**.
+Вместо того чтобы предлагать одну очень мощную функцию,
+Scala 3 предлагает несколько специализированных языковых функций,
+позволяющих программистам напрямую выражать свои намерения:
+
+- **Абстрагирование контекстной информации**. [Using предложения][contextual-using] позволяют программистам абстрагироваться от информации,
+ которая доступна в контексте вызова и должна передаваться неявно.
+ В качестве улучшения по сравнению с имплицитами в Scala 2 предложения _using_ могут указываться по типу,
+ освобождая сигнатуры функций от имен переменных, если на них не ссылаются явно.
+
+- **Предоставление экземпляров классов типов**. [Экземпляры given][contextual-givens] позволяют программистам определять
+ каноническое значение определенного типа. Это делает программирование с классами типов более простым без распространения деталей реализации.
+
+- **Расширение классов задним числом**. В Scala 2 методы расширения должны были быть закодированы с использованием
+ неявных преобразований или неявных классов. Напротив, в Scala 3 [методы расширения][contextual-extension]
+ теперь встроены непосредственно в язык, что приводит к более качественным сообщениям об ошибках и улучшенному выводу типов.
+
+- **Просмотр одного типа как другого**. Неявные преобразования между типами были [переработаны][contextual-conversions] с нуля как экземпляры класса типов `Conversion`.
+
+- **Высокоуровневые контекстные абстракции**. _Совершенно новая_ особенность [контекстных функций][contextual-functions] делает контекстные абстракции функциями первого класса.
+ Они являются важным инструментом для авторов библиотек и позволяют кратко выражать предметно-ориентированные языки.
+
+- **Полезная обратная связь от компилятора**. Если компилятор не может разрешить неявный параметр,
+ теперь он предоставляет [предложения по импорту](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html), которые могут решить проблему.
+
+### Говори, что имеешь в виду: улучшения системы типов
+Помимо значительно улучшенного вывода типов, система типов Scala 3 также предлагает множество новых функций,
+предоставляя вам мощные инструменты для статического выражения инвариантов в типах:
+
+- **Перечисления**. [Enums][enums] были переработаны, чтобы хорошо сочетаться с case-классами
+ и формировать новый стандарт для выражения [алгебраических типов данных][enums-adts].
+
+- **Непрозрачные типы**. Скройте детали реализации за [непрозрачными псевдонимами типов][types-opaque], не платя за это производительностью!
+ Непрозрачные типы заменяют классы значений и позволяют установить барьер абстракции, не вызывая дополнительных накладных расходов на упаковку.
+
+- **Типы пересечения и объединения**. Основание системы типов на новом фундаменте привело к введению новых функций системы типов:
+ экземпляры [типов-пересечений][types-intersection], например `A & B`, являются экземплярами обоих типов `A` и `B`.
+ Экземпляры [типов объединения][types-union], например `A | B`, являются экземплярами либо `A`, либо `B`.
+ Обе конструкции позволяют программистам гибко выражать ограничения типов вне иерархии наследования.
+
+- **Зависимые типы функций**. Scala 2 уже позволяла возвращаемым типам зависеть от (значения) аргументов.
+ В Scala 3 теперь можно абстрагироваться от этого шаблона и выразить [зависимые типы функций][types-dependent].
+ В типе `type F = (e: Entry) => e.Key` тип результата зависит от аргумента!
+
+- **Полиморфные типы функций**. Как и в случае с зависимыми типами функций, Scala 2 поддерживала методы,
+ допускающие параметры типа, но не позволяла программистам абстрагироваться от этих методов.
+ В Scala 3 [полиморфные типы функций][types-polymorphic], например, `[A] => List[A] => List[A]`
+ могут абстрагироваться от функций, которые принимают аргументы типа в дополнение к своим аргументам значения.
+
+- **Лямбда-типы**. То, что нужно было выразить с помощью [плагина компилятора](https://github.com/typelevel/kind-projector) в Scala 2,
+ теперь является функцией первого класса в Scala 3: лямбда-выражения типов — это функции уровня типа,
+ которые можно передавать как аргументы (более высокого типа), не требуя определения вспомогательного типа.
+
+- **Сопоставление типов**. Вместо кодирования вычислений на уровне типов с использованием неявного разрешения,
+ Scala 3 предлагает прямую поддержку [сопоставления типов][types-match].
+ Интеграция вычислений на уровне типов в средство проверки типов позволяет улучшить сообщения об ошибках
+ и устраняет необходимость в сложных кодировках.
+
+
+### Переосмысление: объектно-ориентированное программирование
+Scala всегда была на границе между функциональным программированием и объектно-ориентированным программированием,
+а Scala 3 расширяет границы в обоих направлениях!
+Вышеупомянутые изменения системы типов и редизайн контекстных абстракций делают _функциональное программирование_ проще, чем раньше.
+В то же время следующие новые функции позволяют создавать хорошо структурированные _объектно-ориентированные проекты_
+и поддерживают best practices.
+
+- **Передача параметров**. Трейты становятся ближе к классам и теперь также могут принимать [параметры][oo-trait-parameters],
+ что делает их еще более мощным средством модульной декомпозиции программного обеспечения.
+- **Планирование расширения**. Наследование классов, которые не предназначены для расширения,
+ является давней проблемой объектно-ориентированного проектирования.
+ Чтобы решить эту проблему, [открытые классы][oo-open] требуют, чтобы разработчики библиотек _явно_ помечали классы как открытые.
+- **Скрытие деталей реализации**. Вспомогательные трейты, которые реализуют поведение, иногда не должны быть частью вывода типов.
+ В Scala 3 эти трейты могут быть помечены как [прозрачные][oo-transparent], скрывающие наследование от пользователя (в выводимых типах).
+- **Композиция над наследованием**. Эта фраза часто цитируется, но утомительна для реализации.
+ Не так обстоит дело с [export предложениями][oo-export] в Scala 3 : симметричные по отношению к импорту,
+ предложения export позволяют пользователю определять псевдонимы для выбранных членов объекта.
+- **Больше никаких NullPointerException (экспериментально)**. Scala 3 безопаснее, чем когда-либо:
+ [явное значение null][oo-explicit-null] выводит `null` из иерархии типов, помогая статически отлавливать ошибки;
+ дополнительные проверки для [безопасной инициализации][oo-safe-init] обнаруживают попытки доступа к неинициализированным объектам.
+
+### Зарядка в комплекте: метапрограммирование
+В то время как макросы в Scala 2 были только экспериментальной функцией,
+Scala 3 поставляется с мощным арсеналом инструментов для метапрограммирования.
+[Учебник по макросам]({% link _overviews/scala3-macros/tutorial/index.md %}) содержит подробную информацию о различных возможностях.
+В частности, Scala 3 предлагает следующие функциональности для метапрограммирования:
+
+- **Inline**. В качестве базовой отправной точки [функция inline][meta-inline] позволяет редуцировать значения и методы во время компиляции.
+ Эта простая функция уже охватывает множество вариантов использования
+ и в то же время обеспечивает отправную точку для более продвинутых функций.
+- **Операции времени компиляции**. Пакет [`scala.compiletime`][meta-compiletime] содержит дополнительные функции,
+ которые можно использовать для реализации inline методов.
+- **Блоки кода Quoted**. В Scala 3 добавлена новая функция [квазицитирования кода][meta-quotes],
+ обеспечивающая удобный высокоуровневый интерфейс для создания и анализа кода.
+ Создать код для добавления единицы к единице так же просто, как `'{ 1 + 1 }`.
+- **Reflection API**. Для более продвинутых вариантов использования [quotes.reflect][meta-reflection]
+ предоставляет более детализированный контроль для проверки и создания деревьев программ.
+
+Если вы хотите узнать больше о метапрограммировании в Scala 3, приглашаем вас пройти наш [tutorial][meta-tutorial].
+
+
+[enums]: {{ site.scala3ref }}/enums/enums.html
+[enums-adts]: {{ site.scala3ref }}/enums/adts.html
+
+[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html
+[types-union]: {{ site.scala3ref }}/new-types/union-types.html
+[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html
+[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html
+[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html
+[types-match]: {{ site.scala3ref }}/new-types/match-types.html
+[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html
+
+[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html
+[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html
+[reference]: {{ site.scala3ref }}/overview.html
+[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html
+[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %}
+[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %}
+
+[implicits]: {{ site.scala3ref }}/contextual
+[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html
+[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html
+[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html
+[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html
+[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html
+
+[syntax-summary]: {{ site.scala3ref }}/syntax.html
+[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html
+[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html
+[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html
+
+[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %}
+[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %}
+[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %}
+[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %}
+[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %}
+
+[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html
+[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html
+[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html
+[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html
+[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html
+[oo-export]: {{ site.scala3ref }}/other-new-features/export.html
diff --git a/_ru/scala3/scaladoc.md b/_ru/scala3/scaladoc.md
new file mode 100644
index 0000000000..969b4a4688
--- /dev/null
+++ b/_ru/scala3/scaladoc.md
@@ -0,0 +1,108 @@
+---
+layout: singlepage-overview
+title: Новые возможности Scaladoc
+partof: scala3-scaladoc
+scala3: true
+language: ru
+---
+
+Новая версия Scala 3 поставляется со совершенно новой реализацией генератора документации _Scaladoc_, переписанной с нуля.
+В этой статье вы можете найти основные сведения о новых функциях, которые уже есть или будут представлены в Scaladoc.
+Для общей справки см. руководство по [Scaladoc][scaladoc].
+
+## Новая функциональность
+
+### Markdown синтаксис
+
+Самым большим изменением, представленным в новой версии Scaladoc, является изменение языка по умолчанию для строк документации.
+До сих пор Scaladoc поддерживал только синтаксис Wikidoc.
+Новый Scaladoc по-прежнему может анализировать устаревший синтаксис `Wikidoc`,
+однако Markdown был выбран в качестве основного языка для форматирования комментариев.
+Чтобы переключиться обратно на `Wikidoc`, можно передать глобальный параметр перед запуском задачи `doc`
+или определить его для конкретных комментариев с помощью директивы `@syntax wiki`.
+
+Для получения дополнительной информации о том, как использовать все возможности документации,
+ознакомьтесь с [документацией Scaladoc][scaladoc-docstrings].
+
+### Статический сайт
+
+Scaladoc также предоставляет простой способ создания **статических сайтов** как для документации,
+так и для сообщений в блогах, подобно тому, как это делает Jekyll.
+Благодаря этой функциональности вы можете очень удобно хранить свою документацию вместе со сгенерированным Scaladoc API.
+
+Для получения дополнительной информации о том, как настроить создание статических сайтов,
+ознакомьтесь с главой [Статическая документация][static-documentation].
+
+
+
+### Посты в блоге
+
+Посты в блогах — это особый тип статических сайтов. В руководстве по работе со Scaladoc
+вы можете найти дополнительную информацию о том, как работать с [сообщениями в блогах][built-in-blog].
+
+
+
+### Ссылки на соцсети
+
+Кроме того, Scaladoc предоставляет простой способ настроить [ссылки на социальные сети][social-links], например Twitter или Discord.
+
+{: style="width: 180px"}
+
+## Экспериментальные функции
+
+Следующие функции в настоящее время (май 2021 г.) не являются стабильными для выпуска в scaladoc,
+однако мы рады услышать ваши отзывы.
+У каждой функции есть отдельная ветка на сайте авторов scala-lang, где вы можете поделиться своим мнением.
+
+### Компиляция фрагментов
+
+Одной из экспериментальных возможностей Scaladoc является компилятор фрагментов кода.
+Этот инструмент позволит вам компилировать фрагменты, которые вы прикрепляете к своей строке документации,
+чтобы проверить, действительно ли они ведут себя так, как предполагалось, например, правильно ли компилируются.
+Эта функция очень похожа на инструменты `tut` или `mdoc`, но будет поставляться вместе со Scaladoc,
+что упрощает настройку и интеграцию в ваш проект.
+Создание интерактивных фрагментов — например, предоставление пользователям возможности редактировать
+и компилировать их в браузере — находится на рассмотрении. Но в настоящее время эта функция пока не рассматривается.
+
+Демонстрация:
+* Скрытие кода 
+* Проверка ошибок компиляции 
+* Включение фрагментов 
+
+Для получения дополнительной информации см. [Руководства][snippet-compiler]
+или следите за этой веткой [Scala Contributors](https://contributors.scala-lang.org/t/snippet-validation-in-scaladoc-for-scala-3/4976).
+
+### Поиск по типу
+
+Поиск функций по их символическим именам может занять много времени.
+Вот почему новый scaladoc позволяет искать методы и поля по их типам.
+
+Итак, для объявления:
+
+```
+extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ...
+```
+
+Вместо поиска по `span` мы также можем искать по `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`.
+
+Чтобы использовать эту функциональность, просто введите сигнатуру функции, которую ищете, в строке поиска scaladoc.
+Вот как это работает:
+
+
+
+Эта функция предоставляется поисковой системой [Inkuire](https://github.com/VirtusLab/Inkuire), которая работает для Scala 3 и Kotlin.
+Чтобы быть в курсе развития этой функции, следите за репозиторием [Inkuire](https://github.com/VirtusLab/Inkuire).
+
+Для получения дополнительной информации см. [соответствующую главу][search-engine]
+
+Обратите внимание, что эта функция все еще находится в разработке, поэтому в нее могут быть внесены значительные изменения.
+Если вы столкнулись с ошибкой или у вас есть идея для улучшения, не стесняйтесь создавать issue на
+[Inkuire](https://github.com/VirtusLab/Inkuire/issues/new) или [dotty](https://github.com/lampepfl/dotty/issues/new).
+
+[scaladoc]: /ru/scala3/guides/scaladoc/index.html
+[scaladoc-docstrings]: /ru/scala3/guides/scaladoc/docstrings.html
+[static-documentation]: /ru/scala3/guides/scaladoc/static-site.html
+[built-in-blog]: /ru/scala3/guides/scaladoc/blog.html
+[social-links]: /ru/scala3/guides/scaladoc/settings.html#-social-links
+[search-engine]: /ru/scala3/guides/scaladoc/search-engine.html
+[snippet-compiler]: /ru/scala3/guides/scaladoc/snippet-compiler.html
diff --git a/_ru/scala3/talks.md b/_ru/scala3/talks.md
new file mode 100644
index 0000000000..06467723c2
--- /dev/null
+++ b/_ru/scala3/talks.md
@@ -0,0 +1,73 @@
+---
+layout: singlepage-overview
+title: Обсуждения
+partof: scala3-scaladoc
+scala3: true
+language: ru
+versionSpecific: true
+---
+
+Серия "Давайте поговорим о Scala 3"
+-------------------------------
+
+[Давайте поговорим о Scala 3](https://www.youtube.com/playlist?list=PLTx-VKTe8yLxYQfX_eGHCxaTuWvvG28Ml) — это серия
+коротких (около 15 минут) докладов о Scala 3. Они охватывают различные темы, например, как начать работу,
+как воспользоваться преимуществами новых языковых функций или как перейти со Scala 2.
+
+Обсуждения Scala 3
+----------------
+- (ScalaDays 2019, Lausanne) [Тур по Scala 3](https://www.youtube.com/watch?v=_Rnrx2lo9cw) от [Martin Odersky](http://twitter.com/odersky)
+
+- (ScalaDays 2016, Berlin) [Развитие Scala](https://www.youtube.com/watch?v=GHzWqJKFCk4) от [Martin Odersky](http://twitter.com/odersky) [\[слайды\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016)
+
+- (JVMLS 2015) [Компиляторы — это базы данных](https://www.youtube.com/watch?v=WxyyJyB_Ssc) от [Martin Odersky](http://twitter.com/odersky) [\[слайды\]](http://www.slideshare.net/Odersky/compilers-are-databases)
+
+- (Scala World 2015) [Dotty: изучение будущего Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) от [Dmitry Petrashko](http://twitter.com/darkdimius) [\[слайды\]](https://d-d.me/scalaworld2015/#/).
+ Дмитрий рассказывает о многих новых функциях, которые предлагает Dotty, таких как типы пересечения и объединения,
+ улучшенная инициализация lazy val и многое другое. Дмитрий также рассказывает о внутреннем устройстве Dotty
+ и, в частности, о высоком уровне контекстных абстракций Dotty.
+ Вы познакомитесь со многими основными понятиями, такими как `Denotations`, их эволюция во времени (компиляции),
+ их преобразования и многое другое.
+
+Глубокое погружение в Scala 3
+----------------------
+- (ScalaDays 2019, Lausanne) [Метапрограммирование в Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) от [Nicolas Stucki](https://github.com/nicolasstucki).
+
+- (ScalaDays 2019, Lausanne) [Scala, ориентированная на будущее: промежуточное представление TASTY](https://www.youtube.com/watch?v=zQFjC3zLYwo) от [Guillaume Martres](http://guillaume.martres.me/).
+
+- (Mar 21, 2017) [Dotty Internals 1: Trees & Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8) от [Dmitry Petrashko](http://twitter.com/darkdimius) [\[заметки\]](https://dotty.epfl.ch/docs/internals/dotty-internals-1-notes.html).
+ Это записанная встреча между EPFL и Waterloo, на которой мы представляем первые понятия внутри Dotty: деревья и символы.
+
+- (Mar 21, 2017) [Dotty Internals 2: Types](https://www.youtube.com/watch?v=3gmLIYlGbKc) от [Martin Odersky](http://twitter.com/odersky) и [Dmitry Petrashko](http://twitter.com/darkdimius).
+ Это записанная встреча между EPFL и Waterloo, на которой мы рассказываем, как типы представлены внутри Dotty.
+
+- (Jun 15, 2017) [Dotty Internals 3: Denotations](https://youtu.be/9iPA7zMRGKY) от [Martin Odersky](http://twitter.com/odersky) и [Dmitry Petrashko](http://twitter.com/darkdimius).
+ Это записанная встреча между EPFL и Waterloo, где мы вводим обозначения в Dotty.
+
+- (JVM Language Summit) [How do we make the Dotty compiler fast](https://www.youtube.com/watch?v=9xYoSwnSPz0) от [Dmitry Petrashko](http://twitter.com/darkdimius).
+ [Dmitry Petrashko](http://twitter.com/darkdimius) в общих чертах рассказывает о том, что было сделано для создания Dotty.
+
+- (Typelevel Summit Oslo, May 2016) [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) от
+ Guillaume Martres [\[слайды\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/).
+ Guillaume сосредоточился на некоторых практических улучшениях системы типов, реализованных в Dotty,
+ таких как новый алгоритм вывода параметров типа,
+ который может принимать решения о безопасности типов в большем количестве ситуаций, чем scalac.
+
+- (flatMap(Oslo) 2016) [AutoSpecialization in Dotty](https://vimeo.com/165928176) от [Dmitry Petrashko](http://twitter.com/darkdimius) [\[слайды\]](https://d-d.me/talks/flatmap2016/#/).
+ Dotty Linker анализирует вашу программу и ее зависимости, чтобы применить новую схему специализации.
+ Он основан на нашем опыте Specialization, Miniboxing и проекта Valhalla и значительно уменьшает размер создаваемого байт-кода.
+ И, что лучше всего, он всегда включен, выполняется за кулисами без аннотаций и приводит к ускорению более чем в 20 раз.
+ Кроме того, он "просто работает" с коллекциями Scala.
+
+- (ScalaSphere 2016) [Hacking on Dotty: A live demo](https://www.youtube.com/watch?v=0OOYGeZLHs4) от Guillaume Martres [\[слайды\]](http://guillaume.martres.me/talks/dotty-live-demo/).
+ Guillaume взламывает Dotty: живая демонстрация, во время которой он создает простую фазу компиляции
+ для трассировки вызовов методов во время выполнения.
+
+- (Scala By the Bay 2016) [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) от Guillaume
+ Martres [\[слайды\]](http://guillaume.martres.me/talks/dotty-tutorial/#/).
+ Guillaume предоставляет высокоуровневое представление о конвейере компиляции Dotty.
+
+- (ScalaDays 2015, Amsterdam) [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) от Dmitry Petrashko [\[слайды\]](https://d-d.me/scaladays2015/#/).
+ Дмитрий представляет алгоритм анализа графа вызовов, который реализует Dotty, и преимущества производительности,
+ которые мы можем получить с точки зрения количества методов, размера байт-кода, размера кода JVM
+ и количества объектов, выделенных в конце.
diff --git a/scala3/contribute-to-docs.md b/scala3/contribute-to-docs.md
index a30c99effa..2a9795cada 100644
--- a/scala3/contribute-to-docs.md
+++ b/scala3/contribute-to-docs.md
@@ -2,6 +2,7 @@
layout: singlepage-overview
overview-name: "Scala 3 Documentation"
title: Contributing to the Docs
+languages: ["ru"]
---
## Overview
There are several ongoing efforts to produce high quality documentation for
diff --git a/scala3/new-in-scala3.md b/scala3/new-in-scala3.md
index df85599157..cc3c0add30 100644
--- a/scala3/new-in-scala3.md
+++ b/scala3/new-in-scala3.md
@@ -1,7 +1,7 @@
---
layout: singlepage-overview
title: New in Scala 3
-languages: ["ja","zh-cn","uk"]
+languages: ["ja","zh-cn","uk","ru"]
---
The exciting new version of Scala 3 brings many improvements and
new features. Here we provide you with a quick overview of the most important
diff --git a/scala3/scaladoc.md b/scala3/scaladoc.md
index 6bae13c405..92ba09827f 100644
--- a/scala3/scaladoc.md
+++ b/scala3/scaladoc.md
@@ -2,7 +2,7 @@
layout: singlepage-overview
title: New features for Scaladoc
partof: scala3-scaladoc
-languages: ["uk"]
+languages: ["uk","ru"]
---
The new Scala version 3 comes with a completely new implementation of the documentation generator _Scaladoc_, rewritten from scratch.
diff --git a/scala3/talks.md b/scala3/talks.md
index 3ba01d3588..19539ba13d 100644
--- a/scala3/talks.md
+++ b/scala3/talks.md
@@ -3,7 +3,7 @@ layout: singlepage-overview
title: Talks
scala3: true
partof: scala3-talks
-languages: ["uk"]
+languages: ["uk","ru"]
versionSpecific: true
---