Links to docs from error messages

[mtoy-googly-moogly]

An error message might look like

`Aggregate source cannot be a ${footType.dataType}`

We would like it to show up to a user as

Aggregate source cannot be a string (LINK TO DOCS)

Then clicking on the link the user is taken to a line in a file

---

Aggregate source cannot be a datatype

The path to an aggregate computation (e.g. alpha.beta.sum()) was specified and, except for the final entry in the path, each component must be a join or a record. See Aggregates for more information.

---

I propose making a single file which contains all the error explanations, "error_dictionary.malloynb"

for the text for the above message ....

### Aggregate source cannot be a _datatype_
The path to an aggregate computation (e.g. `alpha.beta.sum()`) was specified and,
except for the final entry in the path, each component must be a join or a record.
See [Aggregates](https://docs.malloydata.dev/documentation/language/aggregates) for more information.

Which would generate the link. (automatically the way that docs are processed)

https://docs/malloydata/dev/documentation/error_dictionary#aggregate-cannot-be-a-em-datatype-em-

Would appear in that file, and then code which generates the error would be

this.log(`Aggregate source cannot be a ${footType.dataType}[aggregate-source-cannot-be-a-em-datatype-em-]`)

This doesn't require any extra infrastructure to support redirection to errors, makes it easy to add errors.

Embedding the link in the error message is a laziness, should probably require extra arguments for the error logging so the link is an explicit piece of meta data, I'll look at the best API once I stat implementing it

Anyway the Extension would then have the data to show a link with an error message, no idea (yet) if there is a way for that to show up in the Problems window.

[mtoy-googly-moogly]

I think I will go this way ... the error message data structure will have a link field, but the utility functions in the compiler which generate error messages will parse out the [link] and fill in the error message data structure

[christopherswenson]

I think it's a super great idea to have links to docs in error messages.

One way I've seen something similar done in other projects is to have every error message also have an error type identifier/code (or both), and when you log the error, you include both the error type and the specific message.

I suggest that instead of manually entering links in the error log calls, we:

• create an enum/ for error types: enum LogType { InvalidAggregateSourceType = "invalid-aggregate-source-type" ... }
• write in code a data structure for error docs: [{ errorId: LogType.InvalidAggregateSourceType, docsMd: "### Aggregate source cannot be a ...", }] (this is in docs code, not Malloy code, so it can be changed without updating the Malloy NPM)
• generate a markdown file containing all error docs from that data structure, with <a id="${logType}"> at the start of each entry
• when logging error messages, specify the error type: log.error(LogType.InvalidAggregateSourceType, "Aggregate source cannot be a ...") then automatically append a line in the "pretty" error message like: "For more information about this error message, see https://malloydata.dev/documentation/errors#[logType]"

[christopherswenson]

We could potentially do a similar thing with experiment IDs and experiment docs.

[mtoy-googly-moogly]

Yes, there are even more things we could do that are even more complicated and more powerful. What exists now is fairly lightweight. I would be happy to listen to the benefits that more process heavy approach brings to the table compared to the MVP that exists now.

The error-code-indirection is mostly used when the messages themselves are also looked up in table, for example if there was an internationalized version of the compiler with locale based error messages.

[christopherswenson]

My main concern here is maintainability. If we had a team of people working on docs making sure they were up-to-date, I think we could get away with the simple approach you've outlined. But since we don't, I think we need a system in place that makes it harder to not document errors, and harder to end up with docs that mention errors that no longer exist. By forcing invocations of errors to attach an error ID, we force the developer to contribute to a catalog of all error types, which will make keeping docs up-to-date easier and more enforceable (because we then have a list of error types that need documentation).

Secondly, by giving each error an ID, even if the text of the error message changes, the URL won't change, which will make URLs a bit more sharable.

[mtoy-googly-moogly]

I concede that point. If, in 12 months, there are tons of annotated error messages, maybe that would make sense as a project. As an experimental feature, I feel OK with waiting to see if that even happens.