Clarify scaladoc documentation, fix typos, fix conflicts

docs/docs/usage/scaladoc/blog.md

@@ -22,14 +22,14 @@ All your blogposts must be put under `blog/_posts` directory.
 │ └── index.html
 ```
 
-If you are using sidebar don't forget to place
+If you are using yaml [sidebar](./staticSite.html#sidebar) don't forget to place
 
 ```
 sidebar:
  - title: Blog
 ```
 
-somewhere inside the tree. Scaladoc will attach under that section all of your blogposts.
+somewhere inside the `yaml` tree representing the sidebar sections. Scaladoc will attach under that section all of your blogposts.
 
 ## Naming convention
 

docs/docs/usage/scaladoc/scaladocDocstrings.md

@@ -4,7 +4,7 @@ title: Scaladoc docstrings - specific Tags and Features
 
 # {{page.title}}
 
-This chapater describes how to write correctly docstrings and how to use all available features of scaladoc.
+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)
 
 
@@ -13,7 +13,7 @@ to API definitions. This can be used from within static documentation and blog
 posts to provide blend-in content.
 
 
-## Where to put scaladoc
+## 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:
 
@@ -29,8 +29,12 @@ Scaladoc comments go before the items they pertain to in a special comment block
  * left margin is on the same column on the
  * first line and on subsequent ones.
  *
- * The closing Scaladoc tag goes on its own,
- * separate line. E.g.
+ * 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
  *
@@ -69,7 +73,7 @@ Scaladoc uses `@<tagname>` tags to provide specific detail fields in the comment
 - `@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.
-- `@usecase` provide a simplified method definition for when the full method definition is too complex or noisy. An example is (in the collections API), providing documentation for methods that omit the implicit canBuildFrom.
+
 
 ### Member grouping tags
 
@@ -78,11 +82,11 @@ These tags are well-suited to larger types or packages, with many members. They
 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
-scalacOptions in (Compile, doc) ++= Seq(
+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.
+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.
 
@@ -108,25 +112,26 @@ Members that do not have a `@group` tag will be listed as “Ungrouped” in the
 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
+### Explicit
 
-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.
+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 extension of `wikidoc` links for referencing convenience.
+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 unrecommended to use it in new projects.
+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:

docs/docs/usage/scaladoc/settings.md

@@ -4,7 +4,7 @@ title: Scaladoc settings
 
 # {{page.title}}
 
-You can find brief information included in this chapter while calling scaladoc with `-help` flag. However it can be a little tricky if one uses sbt `doc` task.
+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
 
@@ -13,7 +13,7 @@ If you want to know what is current state of compatibility with scaladoc old fla
 
 ## Providing settings
 
-Scaladoc accepts settings provided as a string, e. g. `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes` or, if called from sbt,
+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`, e. g. `Compile / doc / scalacOptions ++= Seq("-d", "output", "-project", "my-project")`
 
 ## Overview of all available settings
@@ -31,19 +31,25 @@ The logo of your project that appears in a top left corner. To provide compatibi
 The string message that appears in a footer section. To provide compatibility with Scala2 aliases with `-doc-footer`
 
 ##### -comment-syntax
-The default syntax of comments. Defaults to markdown however wikisyntax can be used.
+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:
+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
@@ -52,34 +58,33 @@ where <source-link> is one of following:
  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 scaladoc.
+\<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
+ €{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>`
 
-Example source links is:
-`-source-links:docs=github://lampepfl/dotty/master#docs`
 
 
 ##### -external-mappings
 
 Mapping between regexes matching classpath entries and external documentation.
-'regex::\[scaladoc|scaladoc|javadoc]::path' syntax is used
 
 Example external mapping is:
 `-external-mappings:.*scala.*::scaladoc3::http://dotty.epfl.ch/api/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/`
 
-##### -social-links
+A mapping is of the form '\<regex>::\[scaladoc3|scaladoc|javadoc]::\<path>'. You can supply several mappings, separated by commas, as shown in the example.
 
-Links to social sites. '[github|twitter|gitter|discord]::link' syntax is used. 'custom::link::white_icon_name::black_icon_name' is also allowed, in this case icons must be present in 'images/'' directory.
+##### -social-links
 
-Example social link is:
+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.
@@ -95,6 +100,8 @@ The file from which the root package documentation should be imported.
 ##### -author
 
 Include authors.
+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
 

docs/docs/usage/scaladoc/staticSite.md

@@ -114,7 +114,7 @@ default table of contents allows you to have subsections - albeit the current
 depth limit is 2 however it accepts both files and directories and latter can be used to provide deeper structures.
 
 The items must provide either `subsection` or `url` but not both at once!
-The only excepiton is `Blog` which is only a `title` and behaves differently.
+The only exception is `Blog` which is only a `title` and behaves differently.
 You can read more about blog [here](blog.md).
 
 ```
@@ -128,11 +128,11 @@ You can read more about blog [here](blog.md).
 
 ## Static resources
 
-You can attach static resources (pdf, images) in your documentation using two dedicated directories:
+You can attach static resources (pdf, images) to your documentation by using two dedicated directories:
 `resources` and `images`. When you upload your assests under any of these directories you can reference them in markdown
 as if they were relatively at the same level.
 
-For example let's look at this situation:
+For example, consider the following situation:
 
 ```
 ├── blog
@@ -148,7 +148,7 @@ For example let's look at this situation:
 
 ```
 
-You can access them directly inside any of the files using markdown links:
+You can refer to the assets from within any of the files using markdown links:
 
 ```
 This is my blogpost. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)

scaladoc/documentation/docs/design.md

@@ -7,11 +7,11 @@ Scaladoc is divided into 3 modules, that are:
 
 ##### scaladoc
 
-This module consist core sourcecode and assets (css, js) used for building Scaladoc.
+This module contains the core source code and assets (css, js) used for building Scaladoc.
 
 ##### scaladoc-js
 
-This module consist Scala sourcecode that is transpiled to JavaScript that is used by scaladoc for:
+This module contains Scala source code that is compiled to JavaScript. It is used by scaladoc for:
 - searchbar
 - social links
 - snippets processor