diff --git a/docs/_docs/usage/cbt-projects.md b/docs/_docs/usage/cbt-projects.md deleted file mode 100644 index 59c9f07d8987..000000000000 --- a/docs/_docs/usage/cbt-projects.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: doc-page -title: "Using Dotty with cbt" ---- - -**NOTE: cbt support for Dotty is experimental and incomplete (for example, -incremental compilation is not supported), we recommend [using Dotty with sbt](sbt-projects.md) for now.** - -cbt comes with built-in Dotty support. Follow the -[cbt tutorial](https://github.com/cvogt/cbt/), then simply extend `Dotty` in the Build class. - -```scala -// build/build.scala -import cbt.* -class Build(val context: Context) extends Dotty { - ... -} -``` - -Also see the [example project](https://github.com/cvogt/cbt/tree/master/examples/dotty-example). diff --git a/docs/_docs/usage/dottydoc.md b/docs/_docs/usage/dottydoc.md deleted file mode 100644 index f7010a0ab3b8..000000000000 --- a/docs/_docs/usage/dottydoc.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -layout: doc-page -title: Dottydoc [Legacy] ---- - -Dottydoc is a tool to generate a combined documentation and API reference for -your project. - -In previous versions of the Scaladoc tool, there is a big divide between what -is documentation and what is API reference. Dottydoc allows referencing, citing -and rendering parts of your API in your documentation, thus allowing the two to -blend naturally. - -To do this, Dottydoc is very similar to what [Jekyll](http://jekyllrb.com/) -provides in form of static site generation. As you probably guessed, this -whole site was created using Dottydoc. - -Creating a site is just as simple as in Jekyll. The site root contains the -layout of the site and all files placed here will be either considered static, -or processed for template expansion. - -The files that are considered for template expansion must end in `*.{html,md}` -and will from here on be referred to as "template files" or "templates". - -A simple "hello world" site could look something like this: - -``` -├── docs -│ └── getting-started.md -└── index.html -``` - -This will give you a site with the following endpoints: - -``` -_site/index.html -_site/docs/getting-started.html -``` - -Just as with Jekyll, the site is rendered in a `_site` directory. - -Using existing Templates and Layouts -==================================== -Dottydoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine -and provides a number of custom filters and tags specific to Scala -documentation. - -In Dottydoc, all templates can contain YAML front-matter. The front-matter -is parsed and put into the `page` variable available in templates via Liquid. - -To perform template expansion, Dottydoc looks at `layout` in the front-matter. -Here's a simple example of the templating system in action, `index.html`: - -```html ---- -layout: main ---- - -

Hello world!

-``` - -With a simple main template like this: - -{% raw %} -```html - - - Hello, world! - - - {{ content }} - - -``` - -Would result in `{{ content }}` being replaced by `

Hello world!

` from -the `index.html` file. -{% endraw %} - -Layouts must be placed in a `_layouts` directory in the site root: - -``` -├── _layouts -│ └── main.html -├── docs -│ └── getting-started.md -└── index.html -``` - -It is also possible to use one of the [default layouts](#default-layouts) that ship with Dottydoc. - -Blog -==== -Dottydoc also allows for a simple blogging platform in the same vein as Jekyll. -Blog posts are placed within the `./_blog/_posts` directory and have to be in -the form `year-month-day-title.{md,html}`. - -An example of this would be: - -``` -├── blog -│ └── _posts -│ └── 2016-12-05-implicit-function-types.md -└── index.html -``` - -To be rendered as templates, each blog post should have front-matter and a -`layout` declaration. - -The posts are also available in the variable `site.subpages` throughout the site. -The fields of these objects are the same as in -`[BlogPost](dotty.tools.dottydoc.staticsite.BlogPost)`. - -Includes -======== -In Liquid, there is a concept of include tags, these are used in templates to -include other de facto templates: - -```html -
- {% raw %}{% include "sidebar.html" %}{% endraw %} -
-``` - -You can leave out the file extension if your include ends in `.html`. - -Includes need to be kept in `_includes` in the site root. Dottydoc provides a -couple of [default includes](#default-includes), but the user-specified -includes may override these. - -An example structure with an include file "sidebar.html": - -``` -├── _includes -│ └── sidebar.html -├── blog -│ ├── _posts -│ │ └── 2016-12-05-implicit-function-types.md -│ └── index.md -└── index.html -``` - -Sidebar -======= -Dottydoc gives you the ability to create your own custom table of contents, -this can either be achieved by overriding the `toc.html` or by -providing a `sidebar.yml` file in the site root: - -```yaml -sidebar: - - title: Blog - url: blog/index.html - - title: Docs - url: docs/index.html - - title: Usage - subsection: - - title: Dottydoc - url: docs/usage/dottydoc.html - - title: sbt-projects - url: docs/usage/sbt-projects.html -``` - -The `sidebar` key is mandatory, as well as `title` for each element. The -default table of contents allows you to have subsections - albeit the current -depth limit is 2 -- we would love to see this changed, contributions welcome! - -The items which have the `subsection` key, may not have a `url` key in the -current scheme. A site root example with this could be: - -``` -├── blog -│ └── _posts -│ └── 2016-12-05-implicit-function-types.md -├── index.html -└── sidebar.yml -``` - -Dottydoc Specific Tags and Behavior -==================================== -Linking to API --------------- -If you for instance, want to link to `scala.collection.immutable.Seq` in a -markdown file, you can simply use the canonical path in your url: - -```markdown -[Seq](scala.collection.immutable.Seq) -``` - -Linking to members is done in the same fashion: - -```markdown -[Seq](scala.collection.immutable.Seq.isEmpty) -``` - -Dottydoc denotes objects by ending their names in "$". To select `List.range` -you'd therefore write: - -```markdown -[List.range](scala.collection.immutable.List$.range) -``` - -Rendering Docstrings --------------------- -Sometimes you end up duplicating the docstring text in your documentation, -therefore Dottydoc makes it easy to render this inline: - -```html -{% raw %}{% docstring "scala.collection.immutable.Seq" %}{% endraw %} -``` - -Other extensions ----------------- -We would love to have your feedback on what you think would be good in order to -render the documentation you want! Perhaps you would like to render method -definitions or members? Let us know by filing -[issues](https://github.com/lampepfl/dotty/issues/new)! - -Default Layouts -=============== -main.html ---------- -A wrapper for all other layouts, includes a default `` with included -JavaScripts and CSS style-sheets. - -### Variables ### -* `content`: placed in `` tag -* `extraCSS`: a list of relative paths to extra CSS style-sheets for the site -* `extraJS`: a list of relative paths to extra JavaScripts for the site -* `title`: the `` of the page - -sidebar.html ------------- -Sidebar uses `main.html` as its parent layout. It adds a sidebar generated from -a YAML file (if exists), as well as the index for the project API. - -### Variables ### -* `content`: placed in a `<div>` with class `content-body` -* `docs`: the API docs generated from supplied source files, this is included by - default and does not need to be specified. - -doc-page.html -------------- -Doc page is used for pages that need a sidebar and provides a small wrapper for -the included {% raw %}`{{ content}}`{% endraw %}. - -api-page.html -------------- -The last two layouts are special, in that they are treated specially by -Dottydoc. The input to the API page is a documented -`[Entity](dotty.tools.dottydoc.model.Entity)`. As such, this page can be changed -to alter the way Dottydoc renders API documentation. - -blog-page.html --------------- -A blog page uses files placed in `./_blog/_posts/` as input to render a blog. - -Default Includes -================ -* `scala-logo.svg`: the scala in Dotty version as svg -* `toc.html`: the default table of contents template diff --git a/docs/_docs/usage/ide-support.md b/docs/_docs/usage/ide-support.md deleted file mode 100644 index 25739b021b78..000000000000 --- a/docs/_docs/usage/ide-support.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: doc-page -title: "IDE support for Scala 3" -movedTo: https://docs.scala-lang.org/scala3/getting-started.html ---- - -This page is deprecated. Please go to the [getting-started](https://docs.scala-lang.org/scala3/getting-started.html) diff --git a/docs/_docs/usage/index.md b/docs/_docs/usage/index.md deleted file mode 100644 index dc0f09eaf547..000000000000 --- a/docs/_docs/usage/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -layout: index -title: Usage ---- diff --git a/docs/_docs/usage/sbt-projects.md b/docs/_docs/usage/sbt-projects.md deleted file mode 100644 index 13a61eff27db..000000000000 --- a/docs/_docs/usage/sbt-projects.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: doc-page -title: "Using Dotty with sbt" ---- - -To try it in your project see the [Getting Started User Guide](https://docs.scala-lang.org/scala3/getting-started.html). diff --git a/docs/_docs/usage/scaladoc/blog.md b/docs/_docs/usage/scaladoc/blog.md deleted file mode 100644 index 85c2d9fa044a..000000000000 --- a/docs/_docs/usage/scaladoc/blog.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -layout: doc-page -title: "Built-in blog" - - - ---- - - -Scaladoc allows you to include a simple blog in your documentation. For now, it -provides only basic features. In the future, we plan to include more advanced -features like tagging or author pages. - -Blog is treated a little differently than regular static sites. This article will help you set up your own blog. - -## Proper directory setup - -All your blogposts must be put under `blog/_posts` directory. - - -``` -├── blog -│ ├── _posts -│ │ └── 2016-12-05-implicit-function-types.md -│ └── index.html -``` - -If you are using yaml [sidebar](./static-site.md#sidebar) don't forget to place - -``` -sidebar: - - title: Blog -``` - -somewhere inside the `yaml` tree representing the sidebar sections. Scaladoc will attach under that section all of your blogposts. - -## Naming convention - -All the blogpost filenames should start with date in numeric format matching `YYYY-MM-DD`. -Example name is `2015-10-23-dotty-compiler-bootstraps.md`. diff --git a/docs/_docs/usage/scaladoc/docstrings.md b/docs/_docs/usage/scaladoc/docstrings.md deleted file mode 100644 index 9935702e10bd..000000000000 --- a/docs/_docs/usage/scaladoc/docstrings.md +++ /dev/null @@ -1,194 +0,0 @@ ---- -layout: doc-page -title: "Docstrings - specific Tags and Features" ---- - -This chapter describes how to correctly write docstrings and how to use all the available features of scaladoc. -Since many things are the same as in the old scaladoc, some parts are reused from this [article](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html) - - -Scaladoc extends Markdown with additional features, such as linking -to API definitions. This can be used from within static documentation and blog -posts to provide blend-in content. - - -## Where to put docstrings - -Scaladoc comments go before the items they pertain to in a special comment block that starts with a /** and ends with a */, like this: - -```scala -/** Start the comment here - * and use the left star followed by a - * white space on every line. - * - * Even on empty paragraph-break lines. - * - * Note that the * on each line is aligned - * with the second * in /** so that the - * left margin is on the same column on the - * first line and on subsequent ones. - * - * Close the comment with *\/ - * - * If you use Scaladoc tags (@param, @group, etc.), - * remember to put them at separate lines with nothing preceding. - * - * For example: - * - * Calculate the square of the given number - * - * @param d the Double to square - * @return the result of squaring d - */ - def square(d: Double): Double = d * d -``` - -In the example above, this Scaladoc comment is associated with the method square since it is right before it in the source code. - -Scaladoc comments can go before fields, methods, classes, traits, objects. -For now, scaladoc doesn't support straightforward solution to document packages. There is a dedicated github -[issue](https://github.com/lampepfl/dotty/issues/11284), where you can check the current status of the problem. - -For class primary constructors which in Scala coincide with the definition of the class itself, a @constructor tag is used to target a comment to be put on the primary constructor documentation rather than the class overview. - -## Tags - -Scaladoc uses `@<tagname>` tags to provide specific detail fields in the comments. These include: - -### Class specific tags - -- `@constructor` placed in the class comment will describe the primary constructor. - -### Method specific tags - -- `@return` detail the return value from a method (one per method). - -### Method, Constructor and/or Class tags - -- `@throws` what exceptions (if any) the method or constructor may throw. -- `@param` detail a value parameter for a method or constructor, provide one per parameter to the method/constructor. -- `@tparam` detail a type parameter for a method, constructor or class. Provide one per type parameter. - -### Usage tags - -- `@see` reference other sources of information like external document links or related entities in the documentation. -- `@note` add a note for pre or post conditions, or any other notable restrictions or expectations. -- `@example` for providing example code or related example documentation. - - -### Member grouping tags - -These tags are well-suited to larger types or packages, with many members. They allow you to organize the Scaladoc page into distinct sections, with each one shown separately, in the order that you choose. - -These tags are not enabled by default! You must pass the -groups flag to Scaladoc in order to turn them on. Typically the sbt for this will look something like: - -```scala -Compile / doc / scalacOptions ++= Seq( - "-groups" -) -``` -Each section should have a single-word identifier that is used in all of these tags, shown as `group` below. By default, that identifier is shown as the title of that documentation section, but you can use @groupname to provide a longer title. - -Typically, you should put @groupprio (and optionally @groupname and @groupdesc) in the Scaladoc for the package/trait/class/object itself, describing what all the groups are, and their order. Then put @group in the Scaladoc for each member, saying which group it is in. - -Members that do not have a `@group` tag will be listed as “Ungrouped” in the resulting documentation. - -- `@group <group>` - mark the entity as a member of the `<group>` group. -- `@groupname <group> <name>` - provide an optional name for the group. `<name>` is displayed as the group header before the group description. -- `@groupdesc <group> <description>` - add optional descriptive text to display under the group name. Supports multiline formatted text. -- `@groupprio <group> <priority>` - control the order of the group on the page. Defaults to 0. Ungrouped elements have an implicit priority of 1000. Use a value between 0 and 999 to set a relative position to other groups. Low values will appear before high values. - -### Other tags - -- `@author` provide author information for the following entity -- `@version` the version of the system or API that this entity is a part of. -- `@since` like `@version` but defines the system or API that this entity was first defined in. -- `@deprecated` marks the entity as deprecated, providing both the replacement implementation that should be used and the version/date at which this entity was deprecated. -- `@syntax <name>` let you change the parser for docstring. The default syntax is markdown, however you can change it using this directive. Currently available syntaxes are `markdown` or `wiki`, e. g. `@syntax wiki` - -### Macros - -- `@define <name> <definition>` allows use of $name in other Scaladoc comments within the same source file which will be expanded to the contents of `<definition>`. - -If a comment is not provided for an entity at the current inheritance level, but is supplied for the overridden entity at a higher level in the inheritance hierarchy, the comment from the super-class will be used. - -Likewise if `@param`, `@tparam`, `@return` and other entity tags are omitted but available from a superclass, those comments will be used. - -### Explicit - -For explicit comment inheritance, use the @inheritdoc tag. - -### Markup - -Scaladoc provides two syntax parsers: `markdown` (default) or `wikidoc`. -It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but not necessary most of the time as markup may be used instead. - -#### Markdown - -Markdown uses [commonmark flavour](https://spec.commonmark.org/current/) with two custom extensions: -- `wikidoc` links for referencing convenience -- `wikidoc` codeblocks with curly braces syntax - - -#### Wikidoc - -Wikidoc is syntax used for scala2 scaladoc. It is supported because of many existing source code, however it is **not** recommended to use it in new projects. -Wikisyntax can be toggled on with flag `-comment-syntax wiki` globally, or with `@syntax wiki` directive in docstring. - -Some of the standard markup available: - -``` -`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]] -``` - -For more info about wiki links look at this [chapter](#linking-to-api) - -Other formatting notes - -- Paragraphs are started with one (or more) blank lines. `*` in the margin for the comment is valid (and should be included) but the line should be blank otherwise. -- Headings are defined with surrounding `=` characters, with more `=` denoting subheadings. E.g. `=Heading=`, `==Sub-Heading==`, etc. -- List blocks are a sequence of list items with the same style and level, with no interruptions from other block styles. Unordered lists can be bulleted using `-`, numbered lists can be denoted using `1.`, `i.`, `I.`, or `a.` for the various numbering styles. In both cases, you must have extra space in front, and more space makes a sub-level. - -The markup for list blocks looks like: - -``` -/** Here is an unordered list: - * - * - First item - * - Second item - * - Sub-item to the second - * - Another sub-item - * - Third item - * - * Here is an ordered list: - * - * 1. First numbered item - * 1. Second numbered item - * i. Sub-item to the second - * i. Another sub-item - * 1. Third item - */ -``` - -### General Notes for Writing Scaladoc Comments - -Concise is nice! Get to the point quickly, people have limited time to spend on your documentation, use it wisely. -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 - -Further information on the formatting and style recommendations can be found in Scala-lang scaladoc style guide. - -## Linking to API - -Scaladoc allows linking to API documentation with Wiki-style links. Linking to -`scala.collection.immutable.List` is as simple as -`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation](./linking.md#definition-links). diff --git a/docs/_docs/usage/scaladoc/index.md b/docs/_docs/usage/scaladoc/index.md deleted file mode 100644 index 7cb4d3b04a6b..000000000000 --- a/docs/_docs/usage/scaladoc/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: index -title: "Scaladoc" ---- - -![scaladoc logo](images/scaladoc-logo.png) - -scaladoc is a tool to generate the API documentation of your Scala 3 projects. It provides similar features to `javadoc` as well as `jekyll` or `docusaurus`. diff --git a/docs/_docs/usage/scaladoc/linking.md b/docs/_docs/usage/scaladoc/linking.md deleted file mode 100644 index daef312700fc..000000000000 --- a/docs/_docs/usage/scaladoc/linking.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -layout: doc-page -title: "Linking documentation" ---- - -Scaladoc's main feature is creating API documentation from code comments. - -By default, the code comments are understood as Markdown, though we also support -Scaladoc's old [Wiki syntax](https://docs.scala-lang.org/style/scaladoc.html). - -## Syntax - -### Definition links - -Our definition link syntax is quite close to Scaladoc's syntax, though we have made some -quality-of-life improvements. - -#### Basic syntax - -A definition link looks as follows: `[[scala.collection.immutable.List]]`. - -Which is to say, a definition link is a sequence of identifiers separated by -`.`. The identifiers can be separated with `#` as well for Scaladoc compatibility. - -By default, an identifier `id` references the first (in source order) entity -named `id`. An identifier can end with `$`, which forces it to refer to a value -(an object, a value, a given); an identifier can also end with `!`, which forces -it to refer to a type (a class, a type alias, a type member). - -The links are resolved relative to the current location in source. That is, when -documenting a class, the links are relative to the entity enclosing the class (a -package, a class, an object); the same applies to documenting definitions. - -Special characters in links can be backslash-escaped, which makes them part of -identifiers instead. For example, `` [[scala.collection.immutable\.List]] `` -references the class named `` `immutable.List` `` in package `scala.collection`. - -#### New syntax - -We have extended Scaladoc definition links to make them a bit more pleasant to -write and read in source. The aim was also to bring the link and Scala syntax -closer together. The new features are: - -1. `package` can be used as a prefix to reference the enclosing package - Example: - ``` - package utils - class C { - def foo = "foo". - } - /** See also [[package.C]]. */ - class D { - def bar = "bar". - } - ``` - The `package` keyword helps make links to the enclosing package shorter - and a bit more resistant to name refactorings. -1. `this` can be used as a prefix to reference the enclosing classlike - Example: - ``` - class C { - def foo = "foo" - /** This is not [[this.foo]], this is bar. */ - def bar = "bar" - } - ``` - Using a Scala keyword here helps make the links more familiar, as well as - helps the links survive class name changes. -1. Backticks can be used to escape identifiers - Example: - ``` - def `([.abusive.])` = ??? - /** TODO: Figure out what [[`([.abusive.])`]] is. */ - def foo = `([.abusive.])` - ``` - Previously (versions 2.x), Scaladoc required backslash-escaping to reference such identifiers. Now (3.x versions), - Scaladoc allows using the familiar Scala backtick quotation. - -#### Why keep the Wiki syntax for links? - -There are a few reasons why we've kept the Wiki syntax for documentation links -instead of reusing the Markdown syntax. Those are: - -1. Nameless links in Markdown are ugly: `[](definition)` vs `[[definition]]` - By far, most links in documentation are nameless. It should be obvious how to - write them. -2. Local member lookup collides with URL fragments: `[](#field)` vs `[[#field]]` -3. Overload resolution collides with MD syntax: `[](meth(Int))` vs `[[meth(Int)]]` -4. Now that we have a parser for the link syntax, we can allow spaces inside (in - Scaladoc one needed to slash-escape those), but that doesn't get recognized - as a link in Markdown: `[](meth(Int, Float))` vs `[[meth(Int, Float)]]` - -None of these make it completely impossible to use the standard Markdown link -syntax, but they make it much more awkward and ugly than it needs to be. On top -of that, Markdown link syntax doesn't even save any characters. diff --git a/docs/_docs/usage/scaladoc/search-engine.md b/docs/_docs/usage/scaladoc/search-engine.md deleted file mode 100644 index a586c25c0a21..000000000000 --- a/docs/_docs/usage/scaladoc/search-engine.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -layout: doc-page -title: "Type-based search" ---- - -Searching for functions by their symbolic names can be time-consuming. -That is why the new scaladoc allows searching for methods and fields by their types. - - -Consider the following extension method definition: -``` -extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ... -``` -Instead of searching for `span` we can also search for `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`. - -To use this feature, type the signature of the member you are looking for in the scaladoc searchbar. This is how it works: - -![]({{ site.baseurl }}images/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif) - -This feature is provided by the [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which works for Scala 3 and Kotlin. To be up-to-date with the development of this feature, follow the [Inkuire repository](https://github.com/VirtusLab/Inkuire). - -## Examples of queries - -Some examples of queries with intended results: -- `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` - -## Query syntax - -In order for a scaladoc searchbar query to be searched using Inkuire instead of the default search engine, the query has to contain the `=>` character sequence. - -Accepted input is similar to a curried function signature in Scala 3. With some differences: -- AndTypes, OrTypes and Functions have to be enclosed in parentheses e.g. `(Int & Any) => String` -- fields and parameterless methods can be found by preceding their type with `=>`, e.g., `=> Int` -- A wildcard `_` can be used to indicate that we want to match any type in a given place e.g. `Long => Double => _` -- Types in the form of single letter e.g. `A` or a letter with a digit `X1` are automatically assumed to be type variables -- Other type variables can be declared just like in polymorphic functions e.g. `[AVariable, AlsoAVariable] => AVariable => AlsoAVariable => AVariable` - -### Working with type aliases and method receivers - -When it comes to how the code is mapped to InkuireDb entries, there are some transformations to make the engine more opinionated (though open to suggestions and changes). Firstly, the receiver (non-module owner) of a function can be treated as a first argument. Automatic currying is also applied, so that the results don't depend on argument lists. When finding matches, `val`s and `def`s are not distinguished. - -So the following declarations should be found by query `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 -... -``` - -When it comes to type aliases, they are desugared on both the declaration and the query signature. This means that for declarations: -``` -type Name = String - -def fromName(name: Name): String -def fromString(str: String): Name -``` -both methods, `fromName` and `fromString`, should be found for queries `Name => Name`, `String => String`, `Name => String` and `String => Name`. - -## How it works - -Inkuire works as a JavaScript worker in the browser thanks to the power of [ScalaJS](https://www.scala-js.org/). - -To enable Inkuire when running scaladoc, add the flag `-Ygenerate-inkuire`. By adding this flag two files are generated: -- `inkuire-db.json` - this is the file containing all the searchable declarations from the currently documented project in a format readable to the Inkuire search engine. -- `inkuire-config.json` - this file contains the locations of the database files that should be searchable from the documentation of the current project. By default, it will be generated with the location of the local db file as well as the default implied locations of database files in [External mappings](https://docs.scala-lang.org/scala3/guides/scaladoc/settings.html#-external-mappings). diff --git a/docs/_docs/usage/scaladoc/settings.md b/docs/_docs/usage/scaladoc/settings.md deleted file mode 100644 index 067967ee58cc..000000000000 --- a/docs/_docs/usage/scaladoc/settings.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -layout: doc-page -title: "Settings" ---- - -This chapter lists the configuration options that can be used when calling scaladoc. Some of the information shown here can be found by calling scaladoc with the `-help` flag. - -## Parity with scaladoc for Scala 2 - -Scaladoc has been rewritten from scratch and some of the features turned out to be useless in the new context. -If you want to know what is current state of compatibility with scaladoc old flags, you can visit this issue for tracking [progress](https://github.com/lampepfl/dotty/issues/11907). - -## Providing settings - -Supply scaladoc settings as command-line arguments, e.g., `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. If called from sbt, update the value of `Compile / doc / scalacOptions` and `Compile / doc / target` respectively, e. g. - -``` -Compile / doc / target ++= Seq("-d", "output") -Compile / doc / scalacOptions ++= Seq("-project", "my-project") -``` - -## Overview of all available settings - -##### -project -The name of the project. To provide compatibility with Scala2 aliases with `-doc-title` - -##### -project-version -The current version of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-version` - -##### -project-logo -The logo of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-logo` - -##### -project-footer -The string message that appears in a footer section. To provide compatibility with Scala2 aliases with `-doc-footer` - -##### -comment-syntax -The styling language used for parsing comments. -Currently we support two syntaxes: `markdown` or `wiki` -If setting is not present, scaladoc defaults `markdown` - -##### -revision -Revision (branch or ref) used to build project project. Useful with sourcelinks to prevent them from pointing always to the newest master that is subject to changes. - -##### -source-links -Source links provide a mapping between file in documentation and code repository. - -Example source links is: -`-source-links:docs=github://lampepfl/dotty/master#docs` - -Accepted formats: - -\<sub-path>=\<source-link> -\<source-link> - -where \<source-link> is one of following: - - `github://<organization>/<repository>[/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://<organization>/<repository>` - 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 - - \<scaladoc-template> - -\<scaladoc-template> 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. - - -Template can defined only by subset of sources defined by path prefix represented by `<sub-path>`. -In such case paths used in templates will be relativized against `<sub-path>` - - - -##### -external-mappings - -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 '\<regex>::\[scaladoc3|scaladoc|javadoc]::\<path>'. You can supply several mappings, separated by commas, as shown in the example. - -##### -social-links - -Links to social sites. For example: - -`-social-links:github::https://github.com/lampepfl/dotty,gitter::https://gitter.im/scala/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. - -##### -skip-by-id - -Identifiers of packages or top-level classes to skip when generating documentation. - -##### -skip-by-regex - -Regexes that match fully qualified names of packages or top-level classes to skip when generating documentation. - -##### -doc-root-content - -The file from which the root package documentation should be imported. - -##### -author - -Adding authors in docstring with `@author Name Surname` by default won't be included in generated html documentation. -If you would like to label classes with authors explicitly, run scaladoc with this flag. - -##### -groups - -Group similar functions together (based on the @group annotation) - -##### -private - -Show all types and members. Unless specified, show only public and protected types and members. - -##### -doc-canonical-base-url - -A base URL to use as prefix and add `canonical` URLs to all pages. The canonical URL may be used by search engines to choose the URL that you want people to see in search results. If unset no canonical URLs are generated. - -##### -siteroot - -A directory containing static files from which to generate documentation. Default directory is `./docs` - -##### -no-link-warnings - -Suppress warnings for ambiguous or incorrect links in members’ lookup. Doesn't affect warnings for incorrect links of assets etc. - -##### -versions-dictionary-url - -A URL pointing to a JSON document containing a dictionary: `version label -> documentation location`. -The JSON file has single property `versions` that holds the dictionary associating the labels of specific versions of the documentation to the URLs pointing to their index.html -Useful for libraries that maintain different versions of their documentation. - -Example JSON file: -``` -{ - "versions": { - "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", - "Nightly": "https://dotty.epfl.ch/docs/index.html" - } -} -``` - -##### -snippet-compiler - -Snippet compiler arguments provide a way to configure snippet type checking. - -This setting accepts a list of arguments in the format: -args := arg{,arg} -arg := [path=]flag -where `path` is a prefix of the path to source files where snippets are located and `flag` is the mode in which snippets will be type checked. - -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. - -The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page](../../reference/other-new-features/opaques.md) - -Example usage: - -`-snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile` - -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 - -##### -Ysnippet-compiler-debug - -Setting this option makes snippet compiler print the snippet as it is compiled (after wrapping). - -##### -Ydocument-synthetic-types - -Include pages providing documentation for the intrinsic types (e. g. Any, Nothing) to the docs. The setting is useful only for stdlib because scaladoc for Scala 3 relies on TASTy files, but we cannot provide them for intrinsic types since they are embedded in the compiler. -All other users should not concern with this setting. diff --git a/docs/_docs/usage/scaladoc/site-versioning.md b/docs/_docs/usage/scaladoc/site-versioning.md deleted file mode 100644 index 8ce52d21b067..000000000000 --- a/docs/_docs/usage/scaladoc/site-versioning.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -layout: doc-page -title: "Site versioning" ---- - -Scaladoc provides a convenient way to switch between different versions of the documentation. The feature is useful if we want to expose older docs for users that didn't migrate to the new version of our library. - -### How to setup it - -The feature was designed for easy scalability with no need to regenerate all scaladocs after adding a new version. To do so a new setting is introduced: `-versions-dictionary-url`. Its argument must be a URL to a JSON document holding information about the locations of specific versions. The JSON file has single property `versions` that holds the dictionary associating the labels of specific versions of the documentation to the URLs pointing to their index.html - -Example JSON file: -``` -{ - "versions": { - "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", - "Nightly": "https://dotty.epfl.ch/docs/index.html" - } -} -``` - -This enforce us to provide the setting while generating docs for each of the versions, however it gives us more flexibility later. If you want to add a version of the API docs next to the previous 5 versions that you have already published, then you only need to upload the new docs to a web server and add a new entry to the JSON file. All versions of the site will now become aware of the new site version. - -The important thing to note is that there is only one JSON file to avoid redundancy and each scaladoc must set up its URL location beforehand, for example, in sbt: - -``` -doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/versions.json") -``` - - -### How does it look from user perspective - -Providing a JSON file via `-versions-dictionary-url` enables scaladoc to link between versions. It is also convenient to be able to change the revision label in the drop-down menu. Everything will change automatically. - -![]({{ site.baseurl }}images/scaladoc/nightly.gif) diff --git a/docs/_docs/usage/scaladoc/static-site.md b/docs/_docs/usage/scaladoc/static-site.md deleted file mode 100644 index 6a1f8db0824c..000000000000 --- a/docs/_docs/usage/scaladoc/static-site.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -layout: doc-page -title: "Static documentation" ---- - -Scaladoc can generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/). -Having a combined tool allows providing interaction between static documentation and API, thus allowing the two to blend naturally. - -Creating a site is just as simple as in Jekyll. The site root contains the -the layout of the site and all files placed there will be either considered static, -or processed for template expansion. - -The files that are considered for template expansion must end in `*.{html,md}` -and will from here on be referred to as "template files" or "templates". - -A simple "hello world" site could look something like this: - -``` -├── docs -│ └── getting-started.md -└── index.html -``` - -This will give you a site with the following files in generated documentation: - -``` -index.html -docs/getting-started.html -``` - -Scaladoc can transform both files and directories (to organize your documentation into a tree-like structure). By default, directories have a title based on the file name and have empty content. It is possible to provide index pages for each section by creating `index.html` or `index.md` (not both) in the dedicated directory. - -## Properties - -Scaladoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine -and provides several custom filters and tags specific to Scala -documentation. - -In Scaladoc, all templates can contain YAML front-matter. The front-matter -is parsed and put into the `page` variable available in templates via Liquid. - -Example front-matter - -``` ---- -title: My custom title ---- -``` - -Scaladoc uses some predefined properties to controls some aspects of page. - -Predefined properties: - -- **title** provide page title that will be used in navigation and HTML metadata. -- **extraCss** additional `.css` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** -- **extraJs** additional `.js` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** -- **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs, etc.) but only token HTML wrapper to provide metadata and resources (js and css files). **This setting is not exported to the template engine.** -- **layout** - predefined layout to use, see below. **This setting is not exported to the template engine.** - - -## Using existing Templates and Layouts - -To perform template expansion, Dottydoc looks at the `layout` field in the front-matter. -Here's a simple example of the templating system in action, `index.html`: - -```html ---- -layout: main ---- - -<h1>Hello world!</h1> -``` - -With a simple main template like this: - -{% raw %} -```html -<html> - <head> - <title>Hello, world! - - - {{ content }} - - -``` - -Would result in `{{ content }}` being replaced by `

Hello world!

` from -the `index.html` file. -{% endraw %} - -Layouts must be placed in a `_layouts` directory in the site root: - -``` -├── _layouts -│ └── main.html -├── docs -│ └── getting-started.md -└── index.html -``` - -## Sidebar - -Scaladoc by default uses layout of files in `docs` directory to create table of content. There is also ability to override it by providing a `sidebar.yml` file in the site root: - -```yaml -sidebar: - - title: Blog - - title: My title - page: my-page1.md - - page: my-page2.md - - page: my-page3/subsection - - title: Reference - subsection: - - page: my-page3.md - - index: my-page4/index.md - subsection: - - page: my-page4/my-page4.md - - title: My subsection - index: my-page5/index.md - subsection: - - page: my-page5/my-page5.md - - index: my-page6/index.md - subsection: - - index: my-page6/my-page6/index.md - subsection: - - page: my-page6/my-page6/my-page6.md -``` - -The `sidebar` key is mandatory. -On each level, you can have three different types of entries: `page`, `blog` or `subsection`. - -`page` is a leaf of the structure and accepts the following attributes: -- `title` (optional) - title of the page -- `page` (mandatory) - path to the file that will represent the page, it can be either html or markdown file to be rendered, there is also the possibility to pass the `directory` path. If so, the scaladoc will render the directory and all its content as if there were no `sidebar.yml` basing on its tree structure and index files. - -The `page` property `subsection` accepts nested nodes, these can be either pages or subsections, which allow you to create tree-like navigation. The attributes are: -- `title` (optional) - title of the page -- `index` (optional) - path to the file that will represent the index file of the subsection, it can be either html or markdown file to be rendered -- `subsection` (mandatory) - nested nodes, can be either pages or subsections - -In `subsection`s, you can omit `title` or `index`, however not specifying any of these properties prevents you from specifying the title of the section. - -`blog` is a special node represented by simple entry `- title: Blog` with no other attributes. All your blog posts will be automatically linked under this section. You can read more about the blog [here](./blog.md). - -``` -├── blog -│ ├── _posts -│ │ └── 2016-12-05-implicit-function-types.md -│ └── index.html -├── index.html -└── sidebar.yml -``` - -## Hierarchy of title - -If the title is specified multiple times, the priority is as follows (from highest to lowest priority): - -#### Page - -1. `title` from the `front-matter` of the markdown/html file -2. `title` property from the `sidebar.yml` property -3. filename - -#### Subsection - -1. `title` from the `front-matter` of the markdown/html index file -2. `title` property from the `sidebar.yml` property -3. filename - -Note that if you skip the `index` file in your tree structure or you don't specify the `title` in the frontmatter, there will be given a generic name `index`. The same applies when using `sidebar.yml` but not specifying `title` nor `index`, just a subsection. Again, a generic `index` name will appear. - - -## Static resources - -You can attach static resources (pdf, images) to your documentation by using two dedicated directories: -`resources` and `images`. After placing your assets under any of these directories, you can reference them in markdown -as if they were relatively at the same level. - -For example, consider the following situation: - -``` -├── blog -│ ├── _posts -│ │ └── 2016-12-05-implicit-function-types.md -│ └── index.html -├── index.html -├── resources -│ └── my_file.pdf -├── images -│ └── my_image.png -└── sidebar.yml - -``` - -You can refer to the assets from within any of the files using markdown links: - -``` -This is my blog post. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)``` diff --git a/docs/_docs/usage/version-numbers.md b/docs/_docs/usage/version-numbers.md deleted file mode 100644 index 660cba4509c7..000000000000 --- a/docs/_docs/usage/version-numbers.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: doc-page -title: "Version numbers" ---- - -**This documentation is outdated! Please find the newer version [here](../contributing/procedures/release.md)**. - -Dotty uses multiple schemes for version numbering. - -Stable releases have version numbers of the form `0.${x}.${y}`, where `x` is a main version and `y` is a bug-fix update id. - -Release candidates version numbers have the form `0.${x}.${y}-RC${z}`. -Every 6 weeks, the latest release candidate is promoted to stable and becomes version `0.${x}.${y}`. -The release candidates let library authors test their code in advance of each -release. Multiple release candidates may be released during each 6 weeks -period to fix regressions and are differentiated by `z`. - -Nightlies have version numbers of the form `0.${x}.${y}-bin-${date}-${sha}-NIGHTLY`. -Every 6 weeks, the latest nightly is promoted to release candidate becomes version `0.${x}.${y}-RC1`. diff --git a/docs/_docs/usage/worksheet-mode-implementation-details.md b/docs/_docs/usage/worksheet-mode-implementation-details.md deleted file mode 100644 index 17c1cc3a2430..000000000000 --- a/docs/_docs/usage/worksheet-mode-implementation-details.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -layout: doc-page -title: "Worksheet Mode - Implementation details" - - - - ---- - - -In brief, the worksheets extend the Language Server Protocol and rely on the -Dotty REPL to evaluate code. - -## Evaluation -Each of the individual expressions and statements of the worksheet is extracted -and passed to the Dotty REPL. After the REPL has finished evaluating one unit of -input, it emits a special delimiter that indicates the end of the output for -this input. (See `dotty.tools.languageserver.worksheet.InputStreamConsumer`) - -This process continues until all input has been evaluated. - -The Dotty REPL is run in a separate JVM. The `Evaluator` (see -`dotty.tools.languageserver.worksheet.Evaluator`) will re-use a JVM if the -configuration of the project hasn't changed. - -## Communication with the client -The worksheets extend the Language Server Protocol and add one request and one -notification. - -### Run worksheet request -The worksheet run request is sent from the client to the server to request that -the server runs a given worksheet and streams the result. - -*Request:* - - - method: `worksheet/run` - - params: `WorksheetRunParams` defined as follows: - ```typescript - interface WorksheetRunParams { - /** - * The worksheet to evaluate. - */ - textDocument: VersionedTextDocumentIdentifier; - } - ``` - -*Response:* - - - result: `WorksheetRunResult` defined as follows: - ```typescript - interface WorksheetRunResult { - /** - * Indicates whether evaluation was successful. - */ - success: boolean; - } - ``` - -### Worksheet output notification -The worksheet output notification is sent from the server to the client to -indicate that worksheet execution has produced some output. - -*Notification:* - - - method: `worksheet/publishOutput` - - params: `WorksheetRunOutput` defined as follows: - ```typescript - interface WorksheetRunOutput { - /** - * The worksheet that produced this output. - */ - textDocument: VersionedTextDocumentIdentifier; - - /** - * The range of the expression that produced this output. - */ - range: Range; - - /** - * The output that has been produced. - */ - content: string; - } - ``` diff --git a/docs/sidebar.yml b/docs/sidebar.yml index e5491331937f..3f4e9af6c3eb 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -1,21 +1,5 @@ index: index.md subsection: - - title: Usage - directory: docs/usage - index: usage/index.md - subsection: - - page: usage/sbt-projects.md - - page: usage/ide-support.md - - page: usage/cbt-projects.md - - title: Scaladoc - index: usage/scaladoc/index.md - subsection: - - page: usage/scaladoc/docstrings.md - - page: usage/scaladoc/linking.md - - page: usage/scaladoc/search-engine.md - - page: usage/scaladoc/settings.md - - page: usage/scaladoc/site-versioning.md - - page: usage/scaladoc/static-site.md - title: Reference directory: docs/reference index: reference/overview.md