mirror of
https://github.com/carbon-language/carbon-lang.git
synced 2026-11-16 01:48:12 +00:00
Lexer diagnostics used a single `const char*` as their source location, which only allowed pointing at a single character rather than a run of characters. This limited the underlining of unrecognized tokens, and also made escape sequence diagnostics particularly strange by stopping at whatever point the lexer discovered the error and pointing only at that location. For example: `"\w"` was reported at the `w`, and `"\x"` at the closing `"`. This change tries to always keep the primary location of a diagnostic the point at which typing (inserting or deleting) might fix the error. So for `"\x"`, `\x` is underlined, but the position is at the `"` as that's where you would type a hex code. The lexer's emitter now takes a special lexing source location that represents either a single position _between_ two characters, a single character, or a range of the source buffer. The lexer diagnostics are updated to construct these for the character range as appropriate. Parser diagnostics for a missing token were located at the _next_ token, which is particularly confusing for terminators like missing `;`s. Now they are located at a position after the previous token, with or without a space depending on the token, but typically on the same line. Diagnostics still sort by how far the parser has read. The parser diagnostics for unclosed groups also now attaches a label to the opening token when it is on a separate line. And the diagnostics for mismatched indent in a multi-line string attaches a label to the closing `'''` that establishes that indent. There are likely more location improvements we should do here, but this seemed like a reasonable incremental improvement and is what Claude found when doing an initial audit. One example where I think we should make further improvements is around suggesting raw identifiers when we find an unexpected `Cpp` or `Core` or `base`. We do this consistently now, but raw identifiers should be rare. A TODO is added for these cases. Assisted-by: Claude Code --------- Co-authored-by: Richard Smith <richard@metafoo.co.uk>
561 lines
26 KiB
Markdown
561 lines
26 KiB
Markdown
# Diagnostics
|
|
|
|
<!--
|
|
Part of the Carbon Language project, under the Apache License v2.0 with LLVM
|
|
Exceptions. See /LICENSE for license information.
|
|
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
|
|
-->
|
|
|
|
<!-- toc -->
|
|
|
|
## Table of contents
|
|
|
|
- [Overview](#overview)
|
|
- [Emitters](#emitters)
|
|
- [Consumers](#consumers)
|
|
- [SortingConsumer](#sortingconsumer)
|
|
- [Producing diagnostics](#producing-diagnostics)
|
|
- [Attaching labels](#attaching-labels)
|
|
- [Context](#context)
|
|
- [Diagnostic registry](#diagnostic-registry)
|
|
- [CARBON_DIAGNOSTIC placement](#carbon_diagnostic-placement)
|
|
- [Choosing what a label marks](#choosing-what-a-label-marks)
|
|
- [Locating lexer and parser diagnostics](#locating-lexer-and-parser-diagnostics)
|
|
- [Diagnostic parameter types](#diagnostic-parameter-types)
|
|
- [Diagnostic message style guide](#diagnostic-message-style-guide)
|
|
- [Alternatives considered](#alternatives-considered)
|
|
- [References](#references)
|
|
|
|
<!-- tocstop -->
|
|
|
|
## Overview
|
|
|
|
The diagnostic code is used by the toolchain to produce output.
|
|
|
|
This document covers how a diagnostic is produced and worded.
|
|
[Diagnostics rendering](/toolchain/docs/diagnostics_rendering.md) covers what a
|
|
diagnostic is made of and how one is drawn on a terminal.
|
|
|
|
## Emitters
|
|
|
|
[`Emitter`s](/toolchain/diagnostics/emitter.h) handle the main formatting of a
|
|
message. It's parameterized on a location type, which `ConvertLoc` translates
|
|
into a standardized DiagnosticLocation of file, line, and column.
|
|
|
|
When emitting, the resulting formatted message is passed to a `Consumer`.
|
|
|
|
## Consumers
|
|
|
|
`Consumer`s handle output of diagnostic messages after they've been formatted by
|
|
an Emitter. Important consumers are:
|
|
|
|
- [ConsoleConsumer](/toolchain/diagnostics/stream_consumer.cpp): prints
|
|
diagnostics to console.
|
|
|
|
- [ErrorTrackingConsumer](/toolchain/diagnostics/consumer.h): counts the
|
|
number of errors produced, particularly so that it can be determined whether
|
|
any errors were encountered.
|
|
|
|
- [SortingConsumer](/toolchain/diagnostics/sorting_consumer.h): buffers and
|
|
sorts diagnostics to provide a more human-understandable order while
|
|
maintaining causal consistency.
|
|
|
|
### SortingConsumer
|
|
|
|
`SortingConsumer` is used by default by `carbon compile`. To see the actual
|
|
emitted order, use `carbon compile --stream-errors`.
|
|
|
|
The current `SortingConsumer` implementation sorts diagnostics based on the
|
|
`last_byte_offset`, which represents the latest token handled by the phase
|
|
emitting the diagnostic. This maintains the causal order of the toolchain's
|
|
traversal.
|
|
|
|
We expect cases where multiple diagnostics are emitted at the same offset,
|
|
particularly when they're emitted at the end of a scope. These can have attached
|
|
locations earlier in the scope, such as variable declarations. In these cases,
|
|
we put non-on-scope diagnostics first, and then sort on-scope diagnostics by
|
|
their start position (line and column).
|
|
|
|
Diagnostic sorting is stable, so that diagnostics from earlier phases are
|
|
printed first if all else is equal.
|
|
|
|
The sorting approach balances several competing needs:
|
|
|
|
- **Causal order**: Developers generally want to fix errors in the order they
|
|
are printed. If fixing error A could also fix error B, A should be printed
|
|
first.
|
|
|
|
- **Human-understandable order**: A human expects diagnostics to follow the
|
|
flow of the file. If all parse errors in a file are printed before any
|
|
semantic check errors, the developer may find it confusing to jump back and
|
|
forth through the file.
|
|
|
|
- **Performance where possible**: On fully correct code with no diagnostics,
|
|
which is our performance priority, this has negligible overhead. When there
|
|
are diagnostics, we try to only sort within the `SortingConsumer`. When
|
|
sorting is not desired (such as tools and IDEs that provide their own
|
|
ordering), it's easy to disable.
|
|
|
|
## Producing diagnostics
|
|
|
|
Diagnostics are used to surface issues from compilation. A simple diagnostic
|
|
looks like:
|
|
|
|
```cpp
|
|
CARBON_DIAGNOSTIC(InvalidCode, Error, "code is invalid");
|
|
emitter.Emit(location, InvalidCode);
|
|
```
|
|
|
|
Here, `CARBON_DIAGNOSTIC` defines a static instance of a diagnostic named
|
|
`InvalidCode` with the associated severity (`Error` or `Warning`).
|
|
|
|
The `Emit` call produces a single instance of the diagnostic. When emitted,
|
|
`"code is invalid"` will be the message used. The type of `location` depends on
|
|
the `DiagnosticEmitter`.
|
|
|
|
A diagnostic with an argument looks like:
|
|
|
|
```cpp
|
|
CARBON_DIAGNOSTIC(InvalidCharacter, Error, "invalid character {0}", char);
|
|
emitter.Emit(location, InvalidCharacter, invalid_char);
|
|
```
|
|
|
|
Here, the additional `char` argument to `CARBON_DIAGNOSTIC` specifies the type
|
|
of an argument to expect for message formatting. The `invalid_char` argument to
|
|
`Emit` provides the matching value. It's then passed along with the diagnostic
|
|
message format to `llvm::formatv` to produce the final diagnostic message.
|
|
|
|
An on-scope diagnostic uses `CARBON_DIAGNOSTIC_ON_SCOPE` which is identical
|
|
other than the macro name. For example:
|
|
|
|
```cpp
|
|
CARBON_DIAGNOSTIC_ON_SCOPE(InvalidInScope, Error, "error inside scope");
|
|
emitter.Emit(location, InvalidInScope);
|
|
```
|
|
|
|
## Attaching labels
|
|
|
|
A label is a range of source attached to a diagnostic, with optional text saying
|
|
what that range has to do with the problem. It is declared with
|
|
`CARBON_DIAGNOSTIC_LABEL`, which takes the category before the format, and is
|
|
attached with `Attach`:
|
|
|
|
```cpp
|
|
CARBON_DIAGNOSTIC(CallArgCountMismatch, Error,
|
|
"{0} argument{0:s} passed to function expecting "
|
|
"{1} argument{1:s}",
|
|
IntAsSelect, IntAsSelect);
|
|
CARBON_DIAGNOSTIC_LABEL(ArgsPassedHere, Primary,
|
|
"{0} argument{0:s} passed here", IntAsSelect);
|
|
CARBON_DIAGNOSTIC_LABEL(InCallToFunction, Info,
|
|
"calling function declared here");
|
|
context.emitter()
|
|
.Build(call_parse_node, CallArgCountMismatch,
|
|
arg_refs.size(), param_refs.size())
|
|
.Attach(args_parse_node, ArgsPassedHere, arg_refs.size())
|
|
.Attach(param_parse_node, InCallToFunction)
|
|
.Emit();
|
|
```
|
|
|
|
A label has a format and arguments of its own, validated the way a message's
|
|
are, so it says only what it needs to about the place it marks. It has no level,
|
|
because it belongs to the message it is attached to.
|
|
|
|
The category is `Primary` for source directly part of the problem and `Info` for
|
|
source that explains it without being part of it. Those two are all there is:
|
|
anything a diagnostic has to say that isn't read against the code it names is
|
|
not a label, and is declared with `CARBON_DIAGNOSTIC_CONTEXT` or
|
|
`CARBON_DIAGNOSTIC_LOCATION_INFO` instead.
|
|
|
|
`Attach` also takes a location alone, with no label:
|
|
|
|
```cpp
|
|
emitter.Build(loc, InvalidCode).Attach(operand_loc).Emit();
|
|
```
|
|
|
|
That marks a range as part of the problem and says nothing about it, which is
|
|
how a diagnostic points at the code its message is about without repeating the
|
|
message against it.
|
|
|
|
Attach every label at a location that reaches source: one that converts to only
|
|
a filename -- an invalid node, code the compiler generated -- leaves its words
|
|
on a row of their own with nothing to point at. Some diagnostics still do that
|
|
today; the goal is to restructure them until none do, and to give a diagnostic
|
|
genuinely about a file as a whole a start-of-file or end-of-file location with
|
|
a rendering of its own.
|
|
|
|
### Context
|
|
|
|
A context states a problem in terms of the operation it happened inside. It is
|
|
not a label: its text is a sentence in its own right, so where a diagnostic has
|
|
one it leads and the message is read against the code like anything else
|
|
explaining it.
|
|
|
|
A context is declared with `CARBON_DIAGNOSTIC_CONTEXT` and registered in a
|
|
scope, so that every diagnostic produced inside it says what larger operation
|
|
was being performed:
|
|
|
|
```cpp
|
|
Diagnostics::ContextScope diagnostic_context(
|
|
&context.emitter(), [&](auto& builder) {
|
|
CARBON_DIAGNOSTIC_CONTEXT(
|
|
QualifiedDeclInIncompleteClassScope,
|
|
"cannot declare a member of incomplete class {0}", SemIR::TypeId);
|
|
builder.Attach(loc_id, QualifiedDeclInIncompleteClassScope,
|
|
context.classes().Get(class_id).self_type_id);
|
|
});
|
|
```
|
|
|
|
This is useful when delegating to another part of Check that may produce many
|
|
different kinds of diagnostic. `CARBON_DIAGNOSTIC_SOFT_CONTEXT` declares a
|
|
fallback: it is dropped when the diagnostic already has a context, which is
|
|
assumed to describe the failure better. `ResolvingSpecificHere` is one: a
|
|
failure while monomorphizing a specific says `unable to monomorphize specific`
|
|
only when no enclosing scope has said what operation needed the specific.
|
|
|
|
An `AnnotationScope` works the same way for labels, attaching one to every
|
|
diagnostic emitted inside it. The two kinds of scope are independent: however
|
|
they nest, a diagnostic gets the label of every `AnnotationScope` it is emitted
|
|
inside and the context of every `ContextScope`, less a soft one dropped as
|
|
above.
|
|
|
|
## Diagnostic registry
|
|
|
|
There is a [registry](/toolchain/diagnostics/kind.def) which all diagnostics
|
|
must be added to. Each diagnostic has a line like:
|
|
|
|
```cpp
|
|
CARBON_DIAGNOSTIC_KIND(InvalidCode)
|
|
```
|
|
|
|
This produces a central enumeration of all diagnostics. The eventual intent is
|
|
to require tests for every diagnostic that can be produced, but that isn't
|
|
currently implemented.
|
|
|
|
Labels, contexts, and location info are not registered. Each is declared where
|
|
it is attached and nowhere else, so there is nothing for a registry to make
|
|
unique and nothing that needs to name one from a distance. Each still carries
|
|
its own name, so `--include-diagnostic-kind` says which one produced a line and
|
|
a test can match on it as it does on a kind.
|
|
|
|
What the registry does for a diagnostic is done for those by
|
|
`check_diagnostics.py`, which reads the declarations and the testdata directly
|
|
-- `label` below stands for any of the three:
|
|
|
|
- Every declared label is attached somewhere. The compiler warns about most of
|
|
these, but not about one declared in a header.
|
|
- Every label is exercised by a `file_test`, which is what `coverage_test`
|
|
does for kinds. `UNCOVERED_LABELS` is the exemption list, and an entry that
|
|
gains a test has to come back out of it.
|
|
- Every name a test matches on is a kind or a label that exists, so renaming
|
|
one doesn't leave a test matching nothing.
|
|
|
|
Being attached does not imply being covered, which is why both are checked. A
|
|
label attached only on a branch no test takes is referenced by the code and
|
|
drawn by nothing, and the kind of the diagnostic it hangs off can be covered
|
|
while the branch never runs.
|
|
|
|
## CARBON_DIAGNOSTIC placement
|
|
|
|
Idiomatically, `CARBON_DIAGNOSTIC` will be adjacent to the `Emit` call. However,
|
|
this is only because many diagnostics can only be produced in one code location.
|
|
If they can be produced in multiple locations, they will be at a higher scope so
|
|
that multiple `Emit` calls can reference them. When in a function,
|
|
`CARBON_DIAGNOSTIC` should be placed as close as possible to the usage so that
|
|
it's easier to see the associated output.
|
|
|
|
## Choosing what a label marks
|
|
|
|
A message's location is underlined across the range it covers, so a diagnostic
|
|
with no label still shows the reader something. What it shows is whatever
|
|
location the code emitting it happened to have, which is usually the whole
|
|
construct the diagnostic was raised on -- and the part that is actually wrong is
|
|
often narrower.
|
|
|
|
So the question for each diagnostic is not whether it marks anything but whether
|
|
it marks the right thing:
|
|
|
|
- Where the message's own location is what the reader should look at, leave it
|
|
alone. Attaching a label with the same range and no text says nothing the
|
|
message's own range didn't.
|
|
|
|
- Where something narrower is what went wrong, attach a primary label naming
|
|
it: the operand rather than the operator, the one argument rather than the
|
|
call.
|
|
|
|
- Give the label words when they point at where a part of the message became
|
|
relevant, and leave it wordless otherwise. A message that says two things
|
|
about two different places should say each of them where it happened:
|
|
`CallArgCountMismatch` marks the call with `1 argument passed here` and the
|
|
declaration with the arity it was declared with. Repeating the message that
|
|
way is worth it, because the reader is being shown where each half of the
|
|
sentence came from.
|
|
|
|
- Where the right range isn't reachable, attach the closest one that is and
|
|
leave a TODO saying which range it should be and what would make it
|
|
available. A diagnostic marking its whole call because nothing names its
|
|
argument list is better than one marking nothing, but the gap is worth
|
|
recording where the next person will find it.
|
|
|
|
- A message that names two types is the clearest case for two labels. An
|
|
operation whose operands don't match reports the interface it looked up not
|
|
being implemented, which names both types and points at neither, so each
|
|
operand is marked with the type it contributed. `BuildBinaryOperator` takes
|
|
a `MissingImplDiagnostic` for this, and installs it as an `AnnotationScope`,
|
|
because the diagnostic is emitted further down where only one operand is
|
|
still in hand.
|
|
|
|
The words belong to the syntax, not to the helper the syntax shares.
|
|
`a * b` has a left and a right operand, `a[i]` has an object and an index,
|
|
and `for (x in r)` has only a range, so each names its own labels rather
|
|
than everything that reaches `BuildBinaryOperator` saying "left" and
|
|
"right".
|
|
|
|
Once the operands carry labels, the message points at whatever they leave
|
|
over rather than at the expression they make up. For an infix operator that
|
|
is the operator itself, which `LocIdForDiagnostics::TokenOnly` names since
|
|
the parse node is the operator token. For `a[i]` the parse node names the
|
|
closing bracket, so the message points at the index -- the operand the
|
|
object failed to accept.
|
|
|
|
- Mark the syntax that required an `impl`, and name the interface in the same
|
|
breath. Which interface a piece of syntax needs is a language rule the
|
|
reader may not know, and the message reports only that one is missing, so
|
|
`AttachOperatorSyntax` marks the operator with `` `*` requires an impl of
|
|
`Core.MulWith` `` and lets the two be read together. That also gives the
|
|
message somewhere to point that is neither operand.
|
|
|
|
A message reporting the same missing `impl` twice for one construct is
|
|
worse than either half of it. A `for` loop looks up `Iterate` to make its
|
|
cursor and again to advance it, so the second is diagnosed only when the
|
|
first succeeded.
|
|
|
|
- Say what the developer wrote, not what it desugared to. Impl lookup for
|
|
`a * b` runs through member access, and reporting that a member of
|
|
`Core.MulWith` can't be accessed describes code nobody typed. Where a
|
|
caller passes the syntax down -- `desugared_loc_id` in
|
|
`PerformCompoundMemberAccess` -- the message drops to the part the syntax
|
|
can't say: which type failed to implement the interface.
|
|
|
|
- Don't narrate the code the label sits under. `` `var` nested within another
|
|
`var` `` marks the keyword, and a label reading ``the invalid `var`
|
|
keyword`` repeats both the source and the message while saying nothing
|
|
about where anything came from. Most parse diagnostics are like this: the
|
|
message already names the token, so the range marks it and says nothing.
|
|
|
|
Some ranges cannot be attached at all, and the reason is worth knowing before
|
|
trying. A diagnostic can only mark source that something in hand still names,
|
|
and several layers discard that on the way:
|
|
|
|
- **Desugaring drops where each operand was written.** An operator becomes a
|
|
call whose arguments are conversion insts created at the operator's
|
|
location, so a diagnostic raised while evaluating that call -- division by
|
|
zero, integer overflow, a shift out of range -- can name the operation but
|
|
not the operand. `SemIR::Converted` keeps an `original_id` for tooling, but
|
|
the argument on this path is not a `Converted`, so following it does not
|
|
reach the operand. `Convert` works around the same gap for
|
|
`ConversionFailure` by holding the expression it was given. Closing it
|
|
properly means the desugaring recording where each operand was written.
|
|
|
|
- **Some scopes have no declaration.** `extend impl` and `impl as` outside a
|
|
class are only ever reached from a namespace -- the file or package -- or
|
|
from a scope with no instruction, so there is nothing to mark as the scope
|
|
they ended up in.
|
|
|
|
Where that is the case, attach nothing and leave a TODO saying which range it
|
|
should be and what would make it available. A label whose location names a file
|
|
but no line draws no anchor and reads as pointing at nothing, which is worse
|
|
than the message alone. `check-toolchain-diagnostics` fails a label no testdata
|
|
reaches, which is how to find one whose location never resolves.
|
|
|
|
The obvious source being a dead end is not the same as no source existing, and
|
|
it is worth one more look before writing the TODO. Deduction's inputs are
|
|
substituted insts with no source, but the argument each one descended from can
|
|
be carried alongside it. `UsedBeforeInitialization` is handed an `InitTombstone`
|
|
rather than the binding, but the binding is still on `FullPatternStack`. In both
|
|
cases the range is somewhere else on a stack that has not been unwound yet.
|
|
|
|
Until a diagnostic is migrated its message location supplies the range, which is
|
|
usually the one column an editor would put a cursor on and rarely an extent
|
|
worth looking at.
|
|
|
|
## Locating lexer and parser diagnostics
|
|
|
|
A lexer or parser diagnostic is about text the developer is about to edit, so
|
|
its message is located where they would put the cursor to start fixing it:
|
|
|
|
- Something missing is located at the point where it would be inserted. A
|
|
point covers no text: it is a `Diagnostics::Loc` with a `length` of zero. A
|
|
missing token is inserted just past the token before it, so a missing `;`
|
|
at the end of a line is located at the end of that line rather than at the
|
|
first token of the next. An opening bracket is inserted against the token
|
|
after it when that token is on the same line, so `expected braced code
|
|
block` in `if (x) return;` is located just before `return`.
|
|
|
|
- Something present but wrong is located at the tokens it covers. A word
|
|
that can't be a name, such as a keyword, in a name's position and followed
|
|
by a token that can follow the name, is taken as the name: the message
|
|
covers it and suggests `r#`.
|
|
|
|
- Something missing at the start of a construct is located at the token
|
|
found in its place. The token before the point belongs to another
|
|
construct, possibly on another line, so an expression statement that starts
|
|
with `=` is reported at the `=` rather than at the end of the statement
|
|
before it.
|
|
|
|
- Inside a token, the lexer locates the message at the point to fix and
|
|
attaches the range of what is malformed, which the snippet underlines
|
|
instead. An unterminated string literal is located where its terminator
|
|
goes and underlines the literal; a `\x` escape without two digits is
|
|
located at the digit that is missing or wrong and underlines the escape.
|
|
|
|
In the lexer, a location is a `Lex::SourceLoc`. A `const char*` into the source
|
|
buffer converts to the one character it points at, `SourceLoc::Before` makes a
|
|
point, and `SourceLoc::Range` makes any other range. A range is never made from
|
|
a bare `const char*`, because converting one to `llvm::StringRef` scans for a
|
|
null byte, and a source buffer isn't guaranteed to have one.
|
|
|
|
In the parser, a location is a `Parse::DiagnosticLoc`. A token converts to one,
|
|
`DiagnosticLoc::Tokens` covers a run of tokens, and `Before` and `After` make
|
|
the points on either side of a token. `Context::PointAfterPreviousToken` and
|
|
`Context::OpeningBracketInsertionPoint` locate most missing tokens.
|
|
|
|
## Diagnostic parameter types
|
|
|
|
Diagnostic parameters should have informative types. We rely on three different
|
|
methods for formatting arguments:
|
|
|
|
- Builtin
|
|
[llvm::formatv](https://llvm.org/doxygen/FormatVariadic_8h_source.html)
|
|
support.
|
|
- This includes `char` and integer types (`int`, `int32_t`, and so on).
|
|
- String types can be added as needed, but stringifying values using the
|
|
methods noted below is preferred.
|
|
- Use `std::string` when allocations are required.
|
|
- `llvm::StringRef` is disallowed due to lifetime issues.
|
|
- `llvm::StringLiteral` is disallowed because format providers such as
|
|
`BoolAsSelect` should work in cases where a `StringLiteral` could be
|
|
used, and because string literal parameters tend to make the
|
|
resulting diagnostics hard to translate.
|
|
- `llvm::format_provider<...>` specializations.
|
|
- `BoolAsSelect` and `IntAsSelect` from
|
|
[format_providers.h](/toolchain/diagnostics/format_providers.h) are
|
|
recommended for many cases, because they allow putting the output string
|
|
in the format.
|
|
- `IntAsSelect` can also be used to support pluralization.
|
|
- Custom providers can also be added for non-translated values. For
|
|
example, `Lex::TokenKind` refers to syntax elements, and so can safely
|
|
have its own format provider.
|
|
- `DiagnosticConverter::ConvertArg` overrides.
|
|
- This can provide additional context to a formatter.
|
|
- For example, formatting `SemIR::NameId` accesses the IR's name list.
|
|
|
|
For `Check`, a custom diagnostic converter is provided that can convert some
|
|
common argument types. This includes some types defined in
|
|
[`check/diagnostic_helpers.h`](/toolchain/check/diagnostic_helpers.h) that exist
|
|
solely to be used as diagnostic parameter types. The types specifically
|
|
supported in `Check` diagnostics are:
|
|
|
|
- For formatting names:
|
|
- `NameId` for a general name. This automatically uses raw identifier
|
|
syntax for names that would collide with keywords.
|
|
- `LibraryNameId` for a library name string, which is formatted as either
|
|
`default library` or `library "foo"`.
|
|
- For formatting types, use the following, in order of preference:
|
|
|
|
- A `TypeOfInstId` parameter takes an `InstId` and formats the type of
|
|
that instruction.
|
|
- An `InstIdAsType` parameter takes an `InstId` for a type expression and
|
|
formats that type expression.
|
|
- A `TypeId` parameter is formatted as a canonical description of the
|
|
type. This should be avoided when possible: `TypeId` has no context
|
|
information, so any information about how the type was written in the
|
|
source program will be lost.
|
|
|
|
The above all include enclosing `` ` ``s around the formatted types. They
|
|
may also include additional information about the type, such as the names
|
|
bound to any aliases in the type, although at present they do not.
|
|
|
|
When a type is formatted within a larger snippet of Carbon code, it can be
|
|
desirable to instead just format the type itself; for this, `*AsRawType`
|
|
parameter types are supported:
|
|
|
|
- `InstIdAsRawType`
|
|
- `TypeIdAsRawType`
|
|
- For integer constants, `TypedInt` can be used to format an `APInt` given its
|
|
type. The type is used to determine the signedness to use for the value.
|
|
|
|
## Diagnostic message style guide
|
|
|
|
We want Carbon's diagnostics to be helpful for developers when they run into an
|
|
error, and phrased consistently across diagnostics. In addition, Carbon
|
|
diagnostics may be mixed with Clang diagnostics when compiling interoperable
|
|
code, so we are borrowing some features of Clang's
|
|
[Diagnostic Wording](https://clang.llvm.org/docs/InternalsManual.html#diagnostic-wording).
|
|
Carbon's diagnostic style aims to balance these concerns. Our style is:
|
|
|
|
- Start diagnostics with a lower case letter or quoted code, and omit trailing
|
|
periods.
|
|
|
|
- Quoted code should be enclosed in backticks, for example: ``"`{0}` is bad"``
|
|
|
|
- Phrase diagnostics as bullet points rather than full sentences. Leave out
|
|
articles unless they're necessary for clarity.
|
|
|
|
- Semicolons can be used to separate sentence fragments.
|
|
|
|
- Diagnostics should describe the situation the toolchain observed. The
|
|
language rule violated can be mentioned if it wouldn't otherwise be clear.
|
|
For example:
|
|
|
|
- `"redeclaration of X"` describes the situation and implies that
|
|
redeclarations are not permitted.
|
|
|
|
- ``"`self` declared in invalid context; can only be declared in implicit
|
|
parameter list"`` describes the language rule.
|
|
|
|
- It's OK for a diagnostic to guess at the developer's intent and provide
|
|
a hint after explaining the situation and the rule, but not as a
|
|
substitute for that. For example, ``"add `as String` to convert `i32` to
|
|
`String`"`` is not sufficient as an error message, but ``"cannot
|
|
implicitly convert `i32` to `String`; add `as String` for explicit
|
|
conversion"`` could be acceptable.
|
|
|
|
- Use "cannot" if needed, but try to use phrasing that doesn't require it.
|
|
Avoid "allowed", "legal", "permitted", "valid", and related wording. For
|
|
example:
|
|
|
|
- ``"`export` in `impl` file"`` rather than
|
|
``"`export` is only allowed in API files"``.
|
|
- ``"`extern library` specifies current library"`` rather than
|
|
`` "`extern library` cannot specify the current library"``.
|
|
|
|
- Try to structure diagnostics such that inputs can be extracted without
|
|
string parsing; prefer [typed parameters](#diagnostic-parameter-types). We
|
|
would like to keep a path for diagnostics to be an API. There can be
|
|
exceptions where this is particularly difficult.
|
|
|
|
- TODO: Should diagnostics be atemporal and non-sequential ("multiple
|
|
declarations of X", "additional declaration here"), present tense but
|
|
sequential ("redeclaration of X", "previous declaration is here"), or
|
|
temporal ("redeclaration of X", "previous declaration was here")? We could
|
|
try to sidestep difference between the latter two by avoiding verbs with
|
|
tense ("previously declared here", "Y declared here", with no is/was).
|
|
|
|
- TODO: When do we put identifiers or expressions in diagnostics, versus
|
|
requiring labels pointing at relevant code? Is it only avoided for values,
|
|
or only allowed for types?
|
|
|
|
- TODO: Lots more things to decide, give examples.
|
|
|
|
## Alternatives considered
|
|
|
|
- [Don't sort diagnostics](/proposals/p006699-diagnostic-sorting.md#dont-sort-diagnostics)
|
|
- [Sort by line and column](/proposals/p006699-diagnostic-sorting.md#sort-by-line-and-column)
|
|
- [Sort by last processed token](/proposals/p006699-diagnostic-sorting.md#sort-by-last-processed-token)
|
|
|
|
## References
|
|
|
|
- Proposal
|
|
[#6699: Sort diagnostics](https://github.com/carbon-language/carbon-lang/pull/6699)
|