From 7a618daddfcb7e64840fbb5cd8f882b8c8c1d7cb Mon Sep 17 00:00:00 2001 From: Igor Matuszewski Date: Wed, 15 May 2024 13:59:26 +0200 Subject: [PATCH] Document the new Diagnostic trait --- .../codegen/runtime/cargo/src/runtime/diagnostic.rs | 13 +++++++++++++ .../cargo/src/runtime/napi_interface/diagnostic.rs | 9 +++++++++ .../runtime/cargo/src/runtime/parse_error.rs | 9 +++++++++ .../src/runtime/napi-bindings/generated/index.d.ts | 11 +++++++++++ .../slang_solidity/src/generated/diagnostic.rs | 13 +++++++++++++ .../src/generated/napi_interface/diagnostic.rs | 9 +++++++++ .../slang_solidity/src/generated/parse_error.rs | 9 +++++++++ .../generated/napi-bindings/generated/index.d.ts | 11 +++++++++++ .../slang_testlang/src/generated/diagnostic.rs | 13 +++++++++++++ .../src/generated/napi_interface/diagnostic.rs | 9 +++++++++ .../slang_testlang/src/generated/parse_error.rs | 9 +++++++++ .../generated/napi-bindings/generated/index.d.ts | 11 +++++++++++ 12 files changed, 126 insertions(+) diff --git a/crates/codegen/runtime/cargo/src/runtime/diagnostic.rs b/crates/codegen/runtime/cargo/src/runtime/diagnostic.rs index 81a100358d..8a478c6fb6 100644 --- a/crates/codegen/runtime/cargo/src/runtime/diagnostic.rs +++ b/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> { None } + /// The severity of this diagnostic. fn severity(&self) -> Severity; + /// The primary message associated with this diagnostic. fn message(&self) -> String; } diff --git a/crates/codegen/runtime/cargo/src/runtime/napi_interface/diagnostic.rs b/crates/codegen/runtime/cargo/src/runtime/napi_interface/diagnostic.rs index 21ba249115..cd057ee9a4 100644 --- a/crates/codegen/runtime/cargo/src/runtime/napi_interface/diagnostic.rs +++ b/crates/codegen/runtime/cargo/src/runtime/napi_interface/diagnostic.rs @@ -24,26 +24,35 @@ impl From for Severity { } } +/// A compiler diagnostic that can be rendered to a user. #[napi(namespace = "diagnostic")] pub struct Diagnostic(pub(crate) Box); #[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() diff --git a/crates/codegen/runtime/cargo/src/runtime/parse_error.rs b/crates/codegen/runtime/cargo/src/runtime/parse_error.rs index 5b14899b11..3a08c8e54e 100644 --- a/crates/codegen/runtime/cargo/src/runtime/parse_error.rs +++ b/crates/codegen/runtime/cargo/src/runtime/parse_error.rs @@ -6,6 +6,9 @@ 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, @@ -13,9 +16,15 @@ pub struct ParseError { } 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 { diff --git a/crates/codegen/runtime/npm/src/runtime/napi-bindings/generated/index.d.ts b/crates/codegen/runtime/npm/src/runtime/napi-bindings/generated/index.d.ts index b3853c8a14..c5fa2f874e 100644 --- a/crates/codegen/runtime/npm/src/runtime/napi-bindings/generated/index.d.ts +++ b/crates/codegen/runtime/npm/src/runtime/napi-bindings/generated/index.d.ts @@ -114,10 +114,21 @@ export namespace diagnostic { Information = 3, Hint = 4, } + /** A compiler diagnostic that can be rendered to a user. */ export class Diagnostic { + /** The severity of this diagnostic. */ severity(): Severity; + /** + * 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. + */ textRange(): text_index.TextRange; + /** The primary message associated with this diagnostic. */ message(): string; + /** The code (i.e. `S0123`), if any, associated with this diagnostic. */ code(): string; } } diff --git a/crates/solidity/outputs/cargo/slang_solidity/src/generated/diagnostic.rs b/crates/solidity/outputs/cargo/slang_solidity/src/generated/diagnostic.rs index 663005d9e5..8479ba860f 100644 --- a/crates/solidity/outputs/cargo/slang_solidity/src/generated/diagnostic.rs +++ b/crates/solidity/outputs/cargo/slang_solidity/src/generated/diagnostic.rs @@ -4,6 +4,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, @@ -12,12 +16,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> { None } + /// The severity of this diagnostic. fn severity(&self) -> Severity; + /// The primary message associated with this diagnostic. fn message(&self) -> String; } diff --git a/crates/solidity/outputs/cargo/slang_solidity/src/generated/napi_interface/diagnostic.rs b/crates/solidity/outputs/cargo/slang_solidity/src/generated/napi_interface/diagnostic.rs index 9659273c99..c0348f495c 100644 --- a/crates/solidity/outputs/cargo/slang_solidity/src/generated/napi_interface/diagnostic.rs +++ b/crates/solidity/outputs/cargo/slang_solidity/src/generated/napi_interface/diagnostic.rs @@ -26,26 +26,35 @@ impl From for Severity { } } +/// A compiler diagnostic that can be rendered to a user. #[napi(namespace = "diagnostic")] pub struct Diagnostic(pub(crate) Box); #[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() diff --git a/crates/solidity/outputs/cargo/slang_solidity/src/generated/parse_error.rs b/crates/solidity/outputs/cargo/slang_solidity/src/generated/parse_error.rs index 347b8cda3a..b3caf11e28 100644 --- a/crates/solidity/outputs/cargo/slang_solidity/src/generated/parse_error.rs +++ b/crates/solidity/outputs/cargo/slang_solidity/src/generated/parse_error.rs @@ -8,6 +8,9 @@ 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, @@ -15,9 +18,15 @@ pub struct ParseError { } 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 { diff --git a/crates/solidity/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts b/crates/solidity/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts index 4ddc87c41d..6d367275e7 100644 --- a/crates/solidity/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts +++ b/crates/solidity/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts @@ -809,10 +809,21 @@ export namespace diagnostic { Information = 3, Hint = 4, } + /** A compiler diagnostic that can be rendered to a user. */ export class Diagnostic { + /** The severity of this diagnostic. */ severity(): Severity; + /** + * 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. + */ textRange(): text_index.TextRange; + /** The primary message associated with this diagnostic. */ message(): string; + /** The code (i.e. `S0123`), if any, associated with this diagnostic. */ code(): string; } } diff --git a/crates/testlang/outputs/cargo/slang_testlang/src/generated/diagnostic.rs b/crates/testlang/outputs/cargo/slang_testlang/src/generated/diagnostic.rs index 663005d9e5..8479ba860f 100644 --- a/crates/testlang/outputs/cargo/slang_testlang/src/generated/diagnostic.rs +++ b/crates/testlang/outputs/cargo/slang_testlang/src/generated/diagnostic.rs @@ -4,6 +4,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, @@ -12,12 +16,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> { None } + /// The severity of this diagnostic. fn severity(&self) -> Severity; + /// The primary message associated with this diagnostic. fn message(&self) -> String; } diff --git a/crates/testlang/outputs/cargo/slang_testlang/src/generated/napi_interface/diagnostic.rs b/crates/testlang/outputs/cargo/slang_testlang/src/generated/napi_interface/diagnostic.rs index 9659273c99..c0348f495c 100644 --- a/crates/testlang/outputs/cargo/slang_testlang/src/generated/napi_interface/diagnostic.rs +++ b/crates/testlang/outputs/cargo/slang_testlang/src/generated/napi_interface/diagnostic.rs @@ -26,26 +26,35 @@ impl From for Severity { } } +/// A compiler diagnostic that can be rendered to a user. #[napi(namespace = "diagnostic")] pub struct Diagnostic(pub(crate) Box); #[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() diff --git a/crates/testlang/outputs/cargo/slang_testlang/src/generated/parse_error.rs b/crates/testlang/outputs/cargo/slang_testlang/src/generated/parse_error.rs index 347b8cda3a..b3caf11e28 100644 --- a/crates/testlang/outputs/cargo/slang_testlang/src/generated/parse_error.rs +++ b/crates/testlang/outputs/cargo/slang_testlang/src/generated/parse_error.rs @@ -8,6 +8,9 @@ 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, @@ -15,9 +18,15 @@ pub struct ParseError { } 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 { diff --git a/crates/testlang/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts b/crates/testlang/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts index 19184237c2..7168e7d5a8 100644 --- a/crates/testlang/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts +++ b/crates/testlang/outputs/npm/package/src/generated/napi-bindings/generated/index.d.ts @@ -142,10 +142,21 @@ export namespace diagnostic { Information = 3, Hint = 4, } + /** A compiler diagnostic that can be rendered to a user. */ export class Diagnostic { + /** The severity of this diagnostic. */ severity(): Severity; + /** + * 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. + */ textRange(): text_index.TextRange; + /** The primary message associated with this diagnostic. */ message(): string; + /** The code (i.e. `S0123`), if any, associated with this diagnostic. */ code(): string; } }