Document Scala compiler error codes #24734
Conversation
|
Rendered examples: |
|
is there an automated process to check for addition of new error codes? |
Not yet but I'll add one |
|
We could also link to these pages from DiagnosticRelatedInformation, it's available in the sbt interfaces. |
|
Ach, no that would have to be another field, which is not exposed here :/ |
|
We could anyway link the codes in metals automatically once this is merged, which will work on all Scala 3 versions |
#24755) Extracted from #24734 Adds support for `sc-opts:` attribute that can be set in Markdown code snippets, allowing to pass additioanl arguments to snippet compiler. This would allow us in #24734 to correctlly document behaviour of snippets producing error codes that require additional compiler options to be activated. Example: ensure that `-Werror` makes given code to actually fail which can be checked with `sc:fail`, ``` ```scala sc:fail sc-opts:-Werror,-explain def exampleShouldError(input: Option[String]): Unit = input match case Some("foo") => ??? ```. ```
…om messages.scala
…erateReferenceDocumentation` (crashed)
… repl, tasty-inspector, staging, etc.
WojciechMazur
force-pushed
the
docs/error-codes
branch
from
b76b889 to
e3f3f86
Compare
| on any expected exceptions. For example: | ||
|
|
||
| ```scala | ||
| try { |
There was a problem hiding this comment.
Should we recoment braceless syntax in these snippets?
There was a problem hiding this comment.
Most of example for other error codes use bracless syntax, I can adjust this one.
| ``` | ||
|
|
||
| It is recommended to use the `NonFatal` extractor to catch all exceptions as it | ||
| correctly handles transfer functions like `return`. |
There was a problem hiding this comment.
Might need an example? What is transfer function?
There was a problem hiding this comment.
No idea, example and description was generated based on -explain description from compiler.
So in fact here we have a duplication, the same example in explain and in description (altough outputs are allowed to change any moment)
3 participants
Resolves #24720
All identified error codes produced by compiler are now documented in the reference docs.
-explain), and examples how to fix given problem.scala -S 3.nightly test --with-compiler project/scripts/checkErrorCodeSnippets.test.scala -- +a +l +cIt 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. :
untiltag for inactive codes containg the last version when given error code was emmitedsincetag for code introduced after 3.0.0 - first stable version when given error is emmitedscala3-compiler, this allows to test changes for manually published versions of the compiler, by providing explicit-S <versionwe can test against any version of the compiler, including locally published ones.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 compileThe changes above were extracted to #24755
Piggy backed changes:
scaladoc/generateReferenceDocumentationstarted 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__.scalafile 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