Adjust headers levels (#15933)

- Increase all header levels in files without h2 headers
- Fix docs starting with h3 headers
- Few other minor header fixes

Author: Florian3k

docs/_docs/internals/backend.md

@@ -30,7 +30,7 @@ BCodeIdiomatic     ---------------->        utilities for code generation, e.g.
 
 The `BTypes.scala` class contains the `BType` class and predefined BTypes
 
-### Data Flow ###
+## Data Flow ##
 Compiler creates a `GenBCode` `Phase`, calls `runOn(compilationUnits)`,
 which calls `run(context)`. This:
 
@@ -51,12 +51,12 @@ which calls `run(context)`. This:
   - `GenBCodePipeline.drainQ3` writes byte arrays to disk
 
 
-### Architecture ###
+## Architecture ##
 The architecture of `GenBCode` is the same as in Scalac. It can be partitioned
 into weakly coupled components (called "subsystems" below):
 
 
-#### (a) The queue subsystem ####
+### (a) The queue subsystem ###
 Queues mediate between processors, queues don't know what each processor does.
 
 The first queue contains AST trees for compilation units, the second queue
@@ -70,7 +70,7 @@ serialization to disk.
 
 This subsystem is described in detail in `GenBCode.scala`
 
-#### (b) Bytecode-level types, BType ####
+### (b) Bytecode-level types, BType ###
 The previous bytecode emitter goes to great lengths to reason about
 bytecode-level types in terms of Symbols.
 
@@ -89,7 +89,7 @@ spec (that's why they aren't documented in `GenBCode`, just read the [JVM 8 spec
 
 All things `BType` can be found in `BCodeGlue.scala`
 
-#### (c) Utilities offering a more "high-level" API to bytecode emission ####
+### (c) Utilities offering a more "high-level" API to bytecode emission ###
 Bytecode can be emitted one opcode at a time, but there are recurring patterns
 that call for a simpler API.
 
@@ -100,7 +100,7 @@ of two strategies.
 All these utilities are encapsulated in file `BCodeIdiomatic.scala`. They know
 nothing about the type checker (because, just between us, they don't need to).
 
-#### (d) Mapping between type-checker types and BTypes ####
+### (d) Mapping between type-checker types and BTypes ###
 So that (c) can remain oblivious to what AST trees contain, some bookkeepers
 are needed:
 
@@ -115,7 +115,7 @@ final def exemplar(csym0: Symbol): Tracked = { ... }
 
 Details in `BTypes.scala`
 
-#### (e) More "high-level" utilities for bytecode emission ####
+### (e) More "high-level" utilities for bytecode emission ###
 In the spirit of `BCodeIdiomatic`, utilities are added in `BCodeHelpers` for
 emitting:
 
@@ -125,5 +125,5 @@ emitting:
 - annotations
 
 
-#### (f) Building an ASM ClassNode given an AST TypeDef ####
+### (f) Building an ASM ClassNode given an AST TypeDef ###
 It's done by `PlainClassBuilder`(see `GenBCode.scala`).

docs/_docs/internals/contexts.md

@@ -16,7 +16,7 @@ The `Context` contains the state of the compiler, for example
   * `typerState` (for example undetermined type variables)
   * ...
 
-### Contexts in the typer ###
+## Contexts in the typer ##
 The type checker passes contexts through all methods and adapts fields where
 necessary, e.g.
 
@@ -26,7 +26,7 @@ case tree: untpd.Block => typedBlock(desugar.block(tree), pt)(ctx.fresh.withNewS
 
 A number of fields in the context are typer-specific (`mode`, `typerState`).
 
-### In other phases ###
+## In other phases ##
 Other phases need a context for many things, for example to access the
 denotation of a symbols (depends on the period). However they typically don't
 need to modify / extend the context while traversing the AST. For these phases
@@ -36,7 +36,7 @@ all members.
 **Careful**: beware of memory leaks. Don't hold on to contexts in long lived
 objects.
 
-### Using contexts ###
+## Using contexts ##
 Nested contexts should be named `ctx` to enable implicit shadowing:
 
 ```scala

docs/_docs/internals/dotc-scalac.md

@@ -6,7 +6,7 @@ title: "Differences between Scalac and Dotty"
 Overview explanation how symbols, named types and denotations hang together:
 [Denotations1]
 
-### Denotation ###
+## Denotation ##
 Comment with a few details: [Denotations2]
 
 A `Denotation` is the result of a name lookup during a given period
@@ -21,7 +21,7 @@ A `Denotation` is the result of a name lookup during a given period
 Denotations of methods have a signature ([Signature1]), which
 uniquely identifies overloaded methods.
 
-#### Denotation vs. SymDenotation ####
+### Denotation vs. SymDenotation ###
 A `SymDenotation` is an extended denotation that has symbol-specific properties
 (that may change over phases)
 * `flags`
@@ -31,7 +31,7 @@ A `SymDenotation` is an extended denotation that has symbol-specific properties
 `SymDenotation` implements lazy types (similar to scalac). The type completer
 assigns the denotation's `info`.
 
-#### Implicit Conversion ####
+### Implicit Conversion ###
 There is an implicit conversion:
 ```scala
 core.Symbols.toDenot(sym: Symbol)(implicit ctx: Context): SymDenotation
@@ -42,7 +42,7 @@ implicit conversion does **not** need to be imported, it is part of the
 implicit scope of the type `Symbol` (check the Scala spec). However, it can
 only be applied if an implicit `Context` is in scope.
 
-### Symbol ###
+## Symbol ##
 * `Symbol` instances have a `SymDenotation`
 * Most symbol properties in the Scala 2 compiler are now in the denotation (in the Scala 3 compiler).
 
@@ -57,7 +57,7 @@ if (sym is Flags.PackageClass)  // Scala 3 (*)
 `(*)` Symbols are implicitly converted to their denotation, see above. Each
 `SymDenotation` has flags that can be queried using the `is` method.
 
-### Flags ###
+## Flags ##
 * Flags are instances of the value class `FlagSet`, which encapsulates a
   `Long`
 * Each flag is either valid for types, terms, or both
@@ -74,7 +74,7 @@ if (sym is Flags.PackageClass)  // Scala 3 (*)
   `ModuleVal` / `ModuleClass` for either of the two.
 * `flags.is(Method | Param)`: true if `flags` has either of the two
 
-### Tree ###
+## Tree ##
 * Trees don't have symbols
   - `tree.symbol` is `tree.denot.symbol`
   - `tree.denot` is `tree.tpe.denot` where the `tpe` is a `NamdedType` (see
@@ -87,7 +87,7 @@ if (sym is Flags.PackageClass)  // Scala 3 (*)
     using `prefix.member(name)`.
 
 
-### Type ###
+## Type ##
  * `MethodType(paramSyms, resultType)` from scalac =>
     `mt @ MethodType(paramNames, paramTypes)`. Result type is `mt.resultType`
 

docs/_docs/internals/syntax-3.1.md

@@ -16,7 +16,7 @@ hexDigit      ::= ‘0’ | … | ‘9’ | ‘A’ | … | ‘F’ | ‘a’ |
 
 Informal descriptions are typeset as `“some comment”`.
 
-### Lexical Syntax
+## Lexical Syntax
 The lexical syntax of Scala is given by the following grammar in EBNF
 form.
 

docs/_docs/internals/syntax.md

@@ -30,7 +30,7 @@ hexDigit      ::= ‘0’ | … | ‘9’ | ‘A’ | … | ‘F’ | ‘a’ |
 
 Informal descriptions are typeset as `“some comment”`.
 
-### Lexical Syntax
+## Lexical Syntax
 
 The lexical syntax of Scala is given by the following grammar in EBNF
 form.

docs/_docs/reference/changed-features/imports.md

@@ -38,13 +38,13 @@ import scala.annotation as ann
 import java as j
 ```
 
-### Migration
+## Migration
 
 To support cross-building, Scala 3.0 supports the old import syntax with `_` for wildcards and `=>` for renamings in addition to the new one. The old syntax
 will be dropped in a future versions. Automatic rewritings from old to new syntax
 are offered under settings `-source 3.1-migration -rewrite`.
 
-### Syntax
+## Syntax
 
 ```
 Import            ::=  ‘import’ ImportExpr {‘,’ ImportExpr}

docs/_docs/reference/changed-features/wildcards.md

@@ -10,7 +10,7 @@ List[?]
 Map[? <: AnyRef, ? >: Null]
 ```
 
-### Motivation
+## Motivation
 
 We would like to use the underscore syntax `_` to stand for an anonymous type parameter, aligning it with its meaning in
 value parameter lists. So, just as `f(_)` is a shorthand for the lambda `x => f(x)`, in the future `C[_]` will be a shorthand
@@ -21,7 +21,7 @@ In the future, `F[_]` will mean the same thing, no matter where it is used.
 We pick `?` as a replacement syntax for wildcard types, since it aligns with
 [Java's syntax](https://docs.oracle.com/javase/tutorial/java/generics/wildcardGuidelines.html).
 
-### Migration Strategy
+## Migration Strategy
 
 The migration to the new scheme is complicated, in particular since the [kind projector](https://github.com/typelevel/kind-projector)
 compiler plugin still uses the reverse convention, with `?` meaning parameter placeholder instead of wildcard. Fortunately, kind projector has added `*` as an alternative syntax for `?`.

docs/_docs/reference/contextual/by-name-context-parameters.md

@@ -59,7 +59,7 @@ val s = summon[Test.Codec[Option[Int]]](
 
 No local given instance was generated because the synthesized argument is not recursive.
 
-### Reference
+## Reference
 
 For more information, see [Issue #1998](https://github.com/lampepfl/dotty/issues/1998)
 and the associated [Scala SIP](https://docs.scala-lang.org/sips/byname-implicits.html).

docs/_docs/reference/contextual/context-functions-spec.md

@@ -74,6 +74,6 @@ See the section on Expressiveness from [Simplicitly: foundations and
 applications of implicit function
 types](https://dl.acm.org/citation.cfm?id=3158130).
 
-### Type Checking
+## Type Checking
 
 After desugaring no additional typing rules are required for context function types.

docs/_docs/reference/contextual/context-functions.md

@@ -48,7 +48,7 @@ For example, continuing with the previous definitions,
   g((ctx: ExecutionContext) ?=> f(3)(using ctx)) // is left as it is
 ```
 
-### Example: Builder Pattern
+## Example: Builder Pattern
 
 Context function types have considerable expressive power. For
 instance, here is how they can support the "builder pattern", where
@@ -112,7 +112,7 @@ With that setup, the table construction code above compiles and expands to:
     }(using $t)
   }
 ```
-### Example: Postconditions
+## Example: Postconditions
 
 As a larger example, here is a way to define constructs for checking arbitrary postconditions using an extension method `ensuring` so that the checked result can be referred to simply by `result`. The example combines opaque type aliases, context function types, and extension methods to provide a zero-overhead abstraction.
 
@@ -146,7 +146,7 @@ val s =
   assert(result == 6)
   result
 ```
-### Reference
+## Reference
 
 For more information, see the [blog article](https://www.scala-lang.org/blog/2016/12/07/implicit-function-types.html),
 (which uses a different syntax that has been superseded).

docs/_docs/reference/contextual/contextual.md

@@ -4,7 +4,7 @@ title: "Contextual Abstractions"
 nightlyOf: https://docs.scala-lang.org/scala3/reference/contextual.html
 ---
 
-### Critique of the Status Quo
+## Critique of the Status Quo
 
 Scala's implicits are its most distinguished feature. They are _the_ fundamental way to abstract over context. They represent a unified paradigm with a great variety of use cases, among them: implementing type classes, establishing context, dependency injection, expressing capabilities, computing new types and proving relationships between them.
 
@@ -46,7 +46,7 @@ Historically, many of these shortcomings come from the way implicits were gradua
 
 Existing Scala programmers by and large have gotten used to the status quo and see little need for change. But for newcomers this status quo presents a big hurdle. I believe if we want to overcome that hurdle, we should take a step back and allow ourselves to consider a radically new design.
 
-### The New Design
+## The New Design
 
 The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental changes:
 

docs/_docs/reference/contextual/derivation.md

@@ -26,7 +26,7 @@ given [T: Show]     : Show[Tree[T]]     = Show.derived
 
 We say that `Tree` is the _deriving type_ and that the `Eq`, `Ordering` and `Show` instances are _derived instances_.
 
-### Types supporting `derives` clauses
+## Types supporting `derives` clauses
 
 All data types can have a `derives` clause. This document focuses primarily on data types which also have a given instance
 of the `Mirror` type class available.
@@ -158,7 +158,7 @@ Note the following properties of `Mirror` types,
 + The methods `ordinal` and `fromProduct` are defined in terms of `MirroredMonoType` which is the type of kind-`*`
   which is obtained from `MirroredType` by wildcarding its type parameters.
 
-### Type classes supporting automatic deriving
+## Type classes supporting automatic deriving
 
 A trait or class can appear in a `derives` clause if its companion object defines a method named `derived`. The
 signature and implementation of a `derived` method for a type class `TC[_]` are arbitrary but it is typically of the
@@ -186,7 +186,7 @@ authors would normally implement a `derived` method in this way, however this wa
 authors of the higher level derivation libraries that we expect typical type class authors will use (for a fully
 worked out example of such a library, see [Shapeless 3](https://github.com/milessabin/shapeless/tree/shapeless-3)).
 
-#### How to write a type class `derived` method using low level mechanisms
+## How to write a type class `derived` method using low level mechanisms
 
 The low-level method we will use to implement a type class `derived` method in this example exploits three new
 type-level constructs in Scala 3: inline methods, inline matches, and implicit searches via  `summonInline` or `summonFrom`. Given this definition of the
@@ -360,7 +360,7 @@ The framework described here enables all three of these approaches without manda
 For a brief discussion on how to use macros to write a type class `derived`
 method please read more at [How to write a type class `derived` method using macros](./derivation-macro.md).
 
-### Deriving instances elsewhere
+## Deriving instances elsewhere
 
 Sometimes one would like to derive a type class instance for an ADT after the ADT is defined, without being able to
 change the code of the ADT itself.  To do this, simply define an instance using the `derived` method of the type class
@@ -374,7 +374,7 @@ Assuming the `Ordering.derived` method has a context parameter of type `Mirror[T
 compiler generated `Mirror` instance for `Option` and the derivation of the instance will be expanded on the right
 hand side of this definition in the same way as an instance defined in ADT companion objects.
 
-### Syntax
+## Syntax
 
 ```
 Template          ::=  InheritClauses [TemplateBody]
@@ -397,7 +397,7 @@ It is equivalent to the old form
 class A extends B with C { ... }
 ```
 
-### Discussion
+## Discussion
 
 This type class derivation framework is intentionally very small and low-level. There are essentially two pieces of
 infrastructure in compiler-generated `Mirror` instances,

docs/_docs/reference/contextual/extension-methods.md

@@ -20,7 +20,7 @@ val circle = Circle(0, 0, 1)
 circle.circumference
 ```
 
-### Translation of Extension Methods
+## Translation of Extension Methods
 
 An extension method translates to a specially labelled method that takes the leading parameter section as its first argument list. The label, expressed
 as `<extension>` here, is compiler-internal. So, the definition of `circumference` above translates to the following method, and can also be invoked as such:
@@ -31,7 +31,7 @@ as `<extension>` here, is compiler-internal. So, the definition of `circumferenc
 assert(circle.circumference == circumference(circle))
 ```
 
-### Operators
+## Operators
 
 The extension method syntax can also be used to define operators. Examples:
 
@@ -63,7 +63,7 @@ compiler preprocesses an infix operation `x +: xs` to `xs.+:(x)`, so the extensi
 method ends up being applied to the sequence as first argument (in other words, the
 two swaps cancel each other out). See [here for details](./right-associative-extension-methods.md).
 
-### Generic Extensions
+## Generic Extensions
 
 It is also possible to extend generic types by adding type parameters to an extension. For instance:
 
@@ -109,7 +109,7 @@ extension [T](x: T)(using n: Numeric[T])
   def + (y: T): T = n.plus(x, y)
 ```
 
-### Collective Extensions
+## Collective Extensions
 
 Sometimes, one wants to define several extension methods that share the same
 left-hand parameter type. In this case one can "pull out" the common parameters into
@@ -166,7 +166,7 @@ extension [T](xs: List[T])(using Ordering[T])
     xs.zipWithIndex.collect { case (x, i) if x <= limit => i }
 ```
 
-### Translation of Calls to Extension Methods
+## Translation of Calls to Extension Methods
 
 To convert a reference to an extension method, the compiler has to know about the extension
 method. We say in this case that the extension method is _applicable_ at the point of reference.
@@ -280,7 +280,7 @@ def position(s: String)(ch: Char, n: Int): Int =
   else n
 ```
 
-### Syntax
+## Syntax
 
 Here are the syntax changes for extension methods and collective extensions relative
 to the [current syntax](../syntax.md).