docs: Update the writing style guide with guidelines for diagnostics - #12770
docs: Update the writing style guide with guidelines for diagnostics#127700x6e wants to merge 1 commit into
Conversation
After refactoring a bunch of code to adhere to these guidelines, it might be useful to make the public so that we can point others at them.
2273ac1 to
700164d
Compare
|
This makes sense to me. Another thing that could be mention is that they shouldn't be ending with a period. (I think we even have a test for that) |
|
Is there a rationale I could add for that? |
I did some archeology to find #275 (comment) |
LeonMatthes
left a comment
LeonMatthes
left a comment
There was a problem hiding this comment.
Thanks for working ont his @0x6e
I added some points that still need discussing in my opinion.
|
|
||
| 1. Use the `Display` implementation for Rust types, if they exists. | ||
| - Rationale: The displayed text is generated from one location, keeping it consistent and allowing it to be updated easily. | ||
| 2. Use single quotes around Slint syntax. |
There was a problem hiding this comment.
| 2. Use single quotes around Slint syntax. | |
| 2. Use single quotes ( ' ) around Slint syntax. |
nit: as a non-native speaker it's good to see the character visually to know which one we mean 😅 (' and not `)
Discussion point: Should we use ` instead? That might render nicely in some LSP implementations 🤔 )
| 1. Use the `Display` implementation for Rust types, if they exists. | ||
| - Rationale: The displayed text is generated from one location, keeping it consistent and allowing it to be updated easily. | ||
| 2. Use single quotes around Slint syntax. | ||
| - Rationale: Emphasize the part of the diagnostic that either causes the error or provides a potential solution. |
There was a problem hiding this comment.
For me that is the wrong rationale tbh.
The span should already point at the cause of the error.
IMO it is about distinguishing between prose and code. 🤔
But we could add two new points based on this:
- The diagnostic should span the smallest piece of code that is causing the issue. Use
notediagnostics if the diagnostic is caused by multiple pieces of code.- Rationale: Emphasize the part of the code that causes the error and might need to be removed/changed to fix it
- Suggest solutions
- Rationale: Many errors/warnings have common solutions. Suggest common solutions when possible, even if they are not always the correct solution.
3 participants
After refactoring a bunch of code to adhere to these guidelines, it might be useful to make the public so that we can point others at them.
Very much a draft PR to aid discussion and give us a starting point.