describe the common issues

Author: bishabosha

_overviews/scala3-contribution/arch-intro.md

@@ -2,7 +2,7 @@
 title: High Level Architecture
 type: chapter
 description: This page introduces the high level architecture for the Scala 3 compiler.
-num: 11
+num: 12
 previous-page: procedures-checklist
 next-page: arch-lifecycle
 ---

_overviews/scala3-contribution/arch-lifecycle.md

@@ -2,7 +2,7 @@
 title: Compiler Overview
 type: section
 description: This page describes the lifecycle for the Scala 3 compiler.
-num: 12
+num: 13
 previous-page: arch-intro
 next-page: arch-phases
 ---

_overviews/scala3-contribution/arch-phases.md

@@ -2,7 +2,7 @@
 title: Compiler Phases
 type: section
 description: This page describes the phases for the Scala 3 compiler.
-num: 13
+num: 14
 previous-page: arch-lifecycle
 next-page: arch-types
 ---

_overviews/scala3-contribution/arch-time.md

@@ -2,7 +2,7 @@
 title: Time in the Compiler
 type: section
 description: This page describes the concepts of time in the Scala 3 compiler.
-num: 15
+num: 16
 previous-page: arch-types
 next-page:
 ---

_overviews/scala3-contribution/arch-types.md

@@ -2,7 +2,7 @@
 title: Compiler Types
 type: section
 description: This page discusses the representation of types in the compiler
-num: 14
+num: 15
 previous-page: arch-phases
 next-page: arch-time
 ---

_overviews/scala3-contribution/procedures-areas.md

@@ -0,0 +1,73 @@
+---
+title: Common Issue Locations
+type: section
+description: This page describes common areas of issues around the Scala 3 compiler.
+num: 7
+previous-page: procedures-navigation
+next-page: procedures-inspection
+---
+
+Many issues are localised to small domains of the compiler and are self-contained,
+here is a non-exhaustive list of such domains, and the files associated with them:
+
+### Pretty Printing of Types and Trees
+
+Objects in the compiler that inherit from [Showable] can be pretty printed.
+The pretty-printing of objects is used in many places, from debug output,
+to user-facing error messages and printing of trees after each phase.
+
+Look in [RefinedPrinter] (or its parent class [PlainPrinter]) for the implementation of pretty printing.
+
+### Content of Error Messages
+
+You can find most error messages defined in [messages] (with IDs defined in [ErrorMessageID]). If the message
+is not defined there, try the `-Ydebug-error` compiler flag, which will print a stack trace leading to the
+production of the error.
+
+### Compiler Generated Given Instances
+
+If the issue lies in given instances provided by the compiler, such as `scala.reflect.ClassTag`,
+`scala.deriving.Mirror`, `scala.reflect.TypeTest`, `scala.CanEqual`, `scala.ValueOf`,
+`scala.reflect.Manifest`, etc, look in [Synthesizer], which provides factories for
+given instances.
+
+### Compiler Generated Methods
+
+Members can be generated for many classes, such as `equals` and `hashCode`
+for case classes and value classes, and `ordinal` and `fromProduct` for Mirrors.
+To change the implementation, see [SyntheticMembers].
+
+### Code Completions
+For suggestions to auto-complete method selections, see [Completion].
+
+### Enum Desugaring
+See [Desugar] and [DesugarEnums].
+
+### Pattern Match Exhaustivity
+See [Space].
+
+### Metaprogramming
+
+#### Quotes Reflection
+See the [quoted runtime package][quotes-impl].
+
+#### Inline match
+See [Inliner].
+
+#### Compiletime Ops Types
+See `tryCompiletimeConstantFold` in [Types].
+
+[Showable]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/printing/Showable.scala
+[PlainPrinter]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/printing/PlainPrinter.scala
+[RefinedPrinter]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/printing/RefinedPrinter.scala
+[ErrorMessageID]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/reporting/ErrorMessageID.scala
+[messages]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/reporting/messages.scala
+[Synthesizer]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/typer/Synthesizer.scala
+[SyntheticMembers]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/SyntheticMembers.scala
+[quotes-impl]: https://github.com/lampepfl/dotty/tree/master/compiler/src/scala/quoted/runtime/impl
+[Inliner]: https://github.com/lampepfl/dotty/tree/master/compiler/src/dotty/tools/dotc/typer/Inliner.scala
+[Types]: https://github.com/lampepfl/dotty/tree/master/compiler/src/dotty/tools/dotc/core/Types.scala
+[Completion]: https://github.com/lampepfl/dotty/tree/master/compiler/src/dotty/tools/dotc/interactive/Completion.scala
+[DesugarEnums]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/ast/DesugarEnums.scala
+[Desugar]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/ast/Desugar.scala
+[Space]: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/transform/patmat/Space.scala

_overviews/scala3-contribution/procedures-cheatsheet.md

@@ -7,18 +7,22 @@ previous-page: procedures-intro
 next-page: procedures-reproduce
 ---
 
+This page is a quick-reference guide for common tasks while working with the compiler.
+For more in-depth explainations, see the rest of this chapter.
+
 ## sbt Commands
 
 The following commands can be run within the shell after running `sbt` in the dotty directory.
 
-| Command                           | Description                                                      |
-|-----------------------------------|------------------------------------------------------------------|
-| `scala3/scalac local/Foo.scala`   | Compile the given file – path relative to the dotty directory.   |
-| `scala3/scala Foo`                | Run class `Foo` with dotty directory on the classpath            |
-| `repl`                            | Start a REPL with the bootstrapped compiler                      |
+| Command                            | Description                                                      |
+|------------------------------------|------------------------------------------------------------------|
+| `scala3-bootstrapped/test`         | Run all tests for Scala 3                                        |
+| `scala3-bootstrapped/publishLocal` | Build Scala 3 for use in local projects                          |
+| `scala3/scalac local/Foo.scala`    | Compile the given file – path relative to the dotty directory.   |
+| `scala3/scala Foo`                 | Run class `Foo` with dotty directory on the classpath            |
+| `repl`                             | Start a REPL with the bootstrapped compiler                      |
+| `testCompilation tests/pos`        | Run test suites on files in the `tests/pos` directory.           |
 | <code>testOnly<br/>dotty.tools.dotc.CompilationTests<br/>-- *pos</code> | Run test `pos` from `CompilationTests` suite. |
-| `testCompilation tests/pos`       | Run test suites on files in the `tests/pos` directory.           |
-| `scala3-bootstrapped/test`        | Run all tests for Scala 3                                        |
 | <code>scala3-compiler/Test/runMain<br/>dotty.tools.printTypes</code> | Print types underlying representation |
 | <code>scala3/scalac -print-tasty<br/>local/out/Foo.tasty</code> | Print the TASTy of top-level class `Foo` |
 

_overviews/scala3-contribution/procedures-checklist.md

@@ -1,8 +1,8 @@
 ---
-title: Checklist before opening a Pull Request
+title: Pull Request Checklist
 type: section
 description: This page describes a checklist before opening a Pull Request to the Scala 3 compiler.
-num: 10
+num: 11
 previous-page: procedures-testing
 next-page: arch-intro
 ---

_overviews/scala3-contribution/procedures-efficiency.md

@@ -1,21 +1,26 @@
 ---
-title: Getting Efficient
+title: Improving Your Workflow
 type: section
 description: This page describes improving efficiency of debugging the Scala 3 compiler.
-num: 8
+num: 9
 previous-page: procedures-inspection
 next-page: procedures-testing
 ---
 
-At the Navigation and Inspections sections, we have covered some techniques of working with the compiler. One repeating theme is that there are certain things that need to be done repeatedly and a lot. These are, e.g.:
+In the previous sections, we have covered some techniques of working with the compiler.
+Some of these techniques can be used repetitively, e.g.:
 
 - Navigating stack frames
 - Printing variables in certain ways
 - Instrumenting variable definitions with tracers
 
-These seemingly tiny and insignificant things take a lot of time. They also reduce productivity: if the cost (in terms of time and effort) of navigating to a stack frame is high, you'll think twice before doing so, and possibly miss valuable information.
+The above procedures often take a lot of time when done manually, reducing productivity:
+as the cost (in terms of time and effort) is high, you may avoid attempting to do so,
+and possibly miss valuable information.
 
-So, if you're doing those things really frequently, it's a good idea to spend some time scripting your editor to allow you to do them fast. E.g. you can set up your editor to take you to a stack frame when you click it or create text editor macros to instrument variables for printing.
+If you're doing those things really frequently, it is recommended to script your editor
+to reduce the number of steps. E.g. navigating to the definition of a stack frame
+part when you click it, or instrumenting variables for printing.
 
 An example of how it is done for Sublime Text 3 is [here](https://github.com/anatoliykmetyuk/scala-debug-sublime).
 

_overviews/scala3-contribution/procedures-inspection.md

@@ -1,9 +1,9 @@
 ---
-title: Inspection
+title: How to Inspect Values
 type: section
 description: This page describes inspecting semantic values in the Scala 3 compiler.
-num: 7
-previous-page: procedures-navigation
+num: 8
+previous-page: procedures-areas
 next-page: procedures-efficiency
 ---