Document Scala compiler error codes

[WojciechMazur]

Resolves #24720

All identified error codes produced by compiler are now documented in the reference docs.

• ~ 200/222 error now have a snippet that show in what circumstances given error might be reported, including the detailed output from the compiler (using -explain), and examples how to fix given problem.
• The inactive error codes contain description, but are not provided with examples
• ~10 active error codes have non-compiling examples - this might require specific setup, eg. for too large implicit search scope, or classpath related issues
• all error codes are validated by running dedicated test-suite:

scala -S 3.nightly test --with-compiler project/scripts/checkErrorCodeSnippets.test.scala  -- +a +l +c

It validates that all error codes (unless explicitlly excluded) are well defined: has example snippet, output errors and solutions. This might also check for additional attributes, eg. :

• until tag for inactive codes containg the last version when given error code was emmited
• since tag for code introduced after 3.0.0 - first stable version when given error is emmited
• created to dedicated tool to manually verify documentation and optionally update the outputs from the failing snippet

 scala -S 3.nightly project/scripts/checkErrorCodeSnippets.scala --with-compiler -- <path to error-code.md> --verbose --update-output

• create a tool to update all error codes (useful for larger changes regarding reporting error codes):

scala -S 3.nightly project/scripts/checkErrorCodeSnippets.scala --with-compiler --main-class=updateAllErrorCodeOutputs 

• Each of the scripts uses scala3-compiler, this allows to test changes for manually published versions of the compiler, by providing explicit -S <version we can test against any version of the compiler, including locally published ones.
• CI now uses these scripts to ensure error codes documentation is consistent

Piggy backs fixes that would be required to have correct assertions in generated scaladoc (would be most likelly cherry-picked before merge): - allow to specific `sc-opts:*` to pass specify scalacOptions that would be passed to the snippetCompiler - show position of snippets that failed to compile

The changes above were extracted to #24755

Piggy backed changes:

• During documentation of error codes several inactive (not used, or never instantiated) errors were found - these were marked as inactive.
• scaladoc/generateReferenceDocumentation started to crash after addition of first Markdown snippet - it was caused by classpath/scaladoc setting issue. The problem was fixed, by removing no longer required __fake__.scala file which was used in Scala 3.1 and earlier to workaround requirement of having at least 1 Scala source.

Documentation itself was generated using LLM agents and requires manual review - mostly for correctness of descriptions, code snippets itself are validated to produce correct error codes unless marked with sc:nocompile (see list of non-reproductible error codes in created tool).
Here's the gist with context used to instrument agents

[WojciechMazur]

Rendered examples:

[bishabosha]

is there an automated process to check for addition of new error codes?

[WojciechMazur]

is there an automated process to check for addition of new error codes?

Not yet but I'll add one

[tgodzik]

We could also link to these pages from DiagnosticRelatedInformation, it's available in the sbt interfaces.

[tgodzik]

Ach, no that would have to be another field, which is not exposed here :/

[tgodzik]

We could anyway link the codes in metals automatically once this is merged, which will work on all Scala 3 versions