expand Message docs

Author: ntBre

crates/ruff_linter/src/message/mod.rs

@@ -42,7 +42,15 @@ mod sarif;
 mod text;
 
 /// Message represents either a diagnostic message corresponding to a rule violation or a syntax
-/// error message raised by the parser.
+/// error message.
+///
+/// All of the information for syntax errors is captured in the underlying [`db::Diagnostic`], while
+/// rule violations can have the additional optional fields like fixes, suggestions, and (parent)
+/// `noqa` offsets.
+///
+/// Note also that the we are (mis-)using the diagnostic's primary message to store the Pascal-case
+/// rule name, such as `MissingNewlineAtEndOfFile`, for use in retrieving the corresponding [`Rule`]
+/// in [`Message::rule`].
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Message {
     pub diagnostic: db::Diagnostic,