Document the new Diagnostic trait

crates/codegen/runtime/cargo/src/runtime/diagnostic.rs

@@ -2,6 +2,10 @@ use std::borrow::Cow;
 
 use crate::text_index::TextRange;
 
+/// The severity of a diagnostic.
+///
+/// Explicitly compatible with the [LSP protocol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticSeverity).
+#[non_exhaustive]
 #[repr(u8)]
 pub enum Severity {
     Error = 1,
@@ -10,12 +14,21 @@ pub enum Severity {
     Hint = 4,
 }
 
+/// A compiler diagnostic that can be rendered to a user.
 pub trait Diagnostic {
+    /// The character range of the source that this diagnostic applies to.
+    ///
+    /// Note that this is not tracking columns, so it is not compatible with LSP's
+    /// [`Position`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#position)
+    /// at the moment.
     fn range(&self) -> TextRange;
+    /// The code (i.e. `S0123`), if any, associated with this diagnostic.
     fn code(&self) -> Option<Cow<'_, str>> {
         None
     }
+    /// The severity of this diagnostic.
     fn severity(&self) -> Severity;
+    /// The primary message associated with this diagnostic.
     fn message(&self) -> String;
 }
 

crates/codegen/runtime/cargo/src/runtime/napi_interface/diagnostic.rs

@@ -24,26 +24,35 @@ impl From<crate::diagnostic::Severity> for Severity {
     }
 }
 
+/// A compiler diagnostic that can be rendered to a user.
 #[napi(namespace = "diagnostic")]
 pub struct Diagnostic(pub(crate) Box<dyn crate::diagnostic::Diagnostic>);
 
 #[napi(namespace = "diagnostic")]
 impl Diagnostic {
+    /// The severity of this diagnostic.
     #[napi]
     pub fn severity(&self) -> Severity {
         self.0.severity().into()
     }
 
+    /// The character range of the source that this diagnostic applies to.
+    ///
+    /// Note that this is not tracking columns, so it is not compatible with LSP's
+    /// [`Position`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#position)
+    /// at the moment.
     #[napi(ts_return_type = "text_index.TextRange")]
     pub fn text_range(&self) -> TextRange {
         self.0.range().into()
     }
 
+    /// The primary message associated with this diagnostic.
     #[napi]
     pub fn message(&self) -> String {
         self.0.message()
     }
 
+    /// The code (i.e. `S0123`), if any, associated with this diagnostic.
     #[napi]
     pub fn code(&self) -> String {
         self.0.code().unwrap_or_default().into_owned()

crates/codegen/runtime/cargo/src/runtime/parse_error.rs

@@ -6,16 +6,25 @@ use crate::diagnostic::{self, Diagnostic};
 use crate::kinds::TokenKind;
 use crate::text_index::TextRange;
 
+/// Represents an error that occurred during parsing.
+///
+/// This could have been caused by a syntax error, or by reaching the end of the file when more tokens were expected.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct ParseError {
     pub(crate) text_range: TextRange,
     pub(crate) tokens_that_would_have_allowed_more_progress: Vec<TokenKind>,
 }
 
 impl ParseError {
+    /// The text range at which the error occurred.
     pub fn text_range(&self) -> &TextRange {
         &self.text_range
     }
+
+    /// Renders the message for this error.
+    pub fn message(&self) -> String {
+        Diagnostic::message(self)
+    }
 }
 
 impl ParseError {