From 226105c4d8b93c85503981bdc35d0ecf99810a1a Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Wed, 7 Aug 2024 07:00:11 +0700 Subject: [PATCH] docs: Fix some broken links and missing backticks. --- README.md | 4 ++-- src/handlers/graphical.rs | 3 ++- src/highlighters/mod.rs | 24 ++++++++++++------------ src/highlighters/syntect.rs | 8 ++++---- src/lib.rs | 4 ++-- src/protocol.rs | 2 +- 6 files changed, 23 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 33022f8c..646047c5 100644 --- a/README.md +++ b/README.md @@ -673,12 +673,12 @@ automatically use the [`syntect`] crate to highlight the `#[source_code]` field of your [`Diagnostic`]. Syntax detection with [`syntect`] is handled by checking 2 methods on the [`SpanContents`] trait, in order: -* [language()](SpanContents::language) - Provides the name of the language +* [`language()`](SpanContents::language) - Provides the name of the language as a string. For example `"Rust"` will indicate Rust syntax highlighting. You can set the language of the [`SpanContents`] produced by a [`NamedSource`] via the [`with_language`](NamedSource::with_language) method. -* [name()](SpanContents::name) - In the absence of an explicitly set +* [`name()`](SpanContents::name) - In the absence of an explicitly set language, the name is assumed to contain a file name or file path. The highlighter will check for a file extension at the end of the name and try to guess the syntax from that. diff --git a/src/handlers/graphical.rs b/src/handlers/graphical.rs index 87fb354b..0aeed580 100644 --- a/src/handlers/graphical.rs +++ b/src/handlers/graphical.rs @@ -178,7 +178,8 @@ impl GraphicalReportHandler { } /// Enable syntax highlighting for source code snippets, using the given - /// [`Highlighter`]. See the [crate::highlighters] crate for more details. + /// [`Highlighter`]. See the [highlighters](crate::highlighters) crate + /// for more details. pub fn with_syntax_highlighting( mut self, highlighter: impl Highlighter + Send + Sync + 'static, diff --git a/src/highlighters/mod.rs b/src/highlighters/mod.rs index d605c1c8..75e7e7f3 100644 --- a/src/highlighters/mod.rs +++ b/src/highlighters/mod.rs @@ -26,16 +26,16 @@ mod syntect; /// A syntax highlighter for highlighting miette [`SourceCode`](crate::SourceCode) snippets. pub trait Highlighter { - /// Creates a new [HighlighterState] to begin parsing and highlighting - /// a [SpanContents]. + /// Creates a new [`HighlighterState`] to begin parsing and highlighting + /// a [`SpanContents`]. /// - /// The [GraphicalReportHandler](crate::GraphicalReportHandler) will call - /// this method at the start of rendering a [SpanContents]. + /// The [`GraphicalReportHandler`](crate::GraphicalReportHandler) will call + /// this method at the start of rendering a [`SpanContents`]. /// - /// The [SpanContents] is provided as input only so that the [Highlighter] + /// The [`SpanContents`] is provided as input only so that the [`Highlighter`] /// can detect language syntax and make other initialization decisions prior /// to highlighting, but it is not intended that the Highlighter begin - /// highlighting at this point. The returned [HighlighterState] is + /// highlighting at this point. The returned [`HighlighterState`] is /// responsible for the actual rendering. fn start_highlighter_state<'h>( &'h self, @@ -46,12 +46,12 @@ pub trait Highlighter { /// A stateful highlighter that incrementally highlights lines of a particular /// source code. /// -/// The [GraphicalReportHandler](crate::GraphicalReportHandler) +/// The [`GraphicalReportHandler`](crate::GraphicalReportHandler) /// will create a highlighter state by calling -/// [start_highlighter_state](Highlighter::start_highlighter_state) at the +/// [`start_highlighter_state`](Highlighter::start_highlighter_state) at the /// start of rendering, then it will iteratively call -/// [highlight_line](HighlighterState::highlight_line) to render individual -/// highlighted lines. This allows [Highlighter] implementations to maintain +/// [`highlight_line`](HighlighterState::highlight_line) to render individual +/// highlighted lines. This allows [`Highlighter`] implementations to maintain /// mutable parsing and highlighting state. pub trait HighlighterState { /// Highlight an individual line from the source code by returning a vector of [Styled] @@ -59,9 +59,9 @@ pub trait HighlighterState { fn highlight_line<'s>(&mut self, line: &'s str) -> Vec>; } -/// Arcified trait object for Highlighter. Used internally by [GraphicalReportHandler] +/// Arcified trait object for Highlighter. Used internally by [`GraphicalReportHandler`] /// -/// Wrapping the trait object in this way allows us to implement Debug and Clone. +/// Wrapping the trait object in this way allows us to implement `Debug` and `Clone`. #[derive(Clone)] #[repr(transparent)] pub(crate) struct MietteHighlighter(Arc); diff --git a/src/highlighters/syntect.rs b/src/highlighters/syntect.rs index 69ed0159..538124ca 100644 --- a/src/highlighters/syntect.rs +++ b/src/highlighters/syntect.rs @@ -20,7 +20,7 @@ use crate::{ use super::BlankHighlighterState; -/// Highlights miette [SourceCode] with the [syntect](https://docs.rs/syntect/latest/syntect/) highlighting crate. +/// Highlights miette [`SpanContents`] with the [syntect](https://docs.rs/syntect/latest/syntect/) highlighting crate. /// /// Currently only 24-bit truecolor output is supported due to syntect themes /// representing color as RGBA. @@ -81,7 +81,7 @@ impl SyntectHighlighter { ) } - /// Determine syntect SyntaxReference to use for given SourceCode + /// Determine syntect [`SyntaxReference`] to use for given [`SpanContents`]. fn detect_syntax(&self, contents: &dyn SpanContents<'_>) -> Option<&syntect::SyntaxReference> { // use language if given if let Some(language) = contents.language() { @@ -105,7 +105,7 @@ impl SyntectHighlighter { } } -/// Stateful highlighting iterator for [SyntectHighlighter] +/// Stateful highlighting iterator for [`SyntectHighlighter`]. #[derive(Debug)] pub(crate) struct SyntectHighlighterState<'h> { syntax_set: &'h syntect::SyntaxSet, @@ -133,7 +133,7 @@ impl<'h> HighlighterState for SyntectHighlighterState<'h> { } } -/// Convert syntect [syntect::Style] into owo_colors [Style] */ +/// Convert syntect [`syntect::Style`] into `owo_colors` [`Style`] #[inline] fn convert_style(syntect_style: syntect::Style, use_bg_color: bool) -> Style { if use_bg_color { diff --git a/src/lib.rs b/src/lib.rs index a42f4fad..295dfcb3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -674,12 +674,12 @@ //! field of your [`Diagnostic`]. //! //! Syntax detection with [`syntect`] is handled by checking 2 methods on the [`SpanContents`] trait, in order: -//! * [language()](SpanContents::language) - Provides the name of the language +//! * [`language()`](SpanContents::language) - Provides the name of the language //! as a string. For example `"Rust"` will indicate Rust syntax highlighting. //! You can set the language of the [`SpanContents`] produced by a //! [`NamedSource`] via the [`with_language`](NamedSource::with_language) //! method. -//! * [name()](SpanContents::name) - In the absence of an explicitly set +//! * [`name()`](SpanContents::name) - In the absence of an explicitly set //! language, the name is assumed to contain a file name or file path. //! The highlighter will check for a file extension at the end of the name and //! try to guess the syntax from that. diff --git a/src/protocol.rs b/src/protocol.rs index d3ee9ca7..7f09d4d2 100644 --- a/src/protocol.rs +++ b/src/protocol.rs @@ -523,7 +523,7 @@ impl<'a> MietteSpanContents<'a> { } } - /// Sets the [`language`](SourceCode::language) for syntax highlighting. + /// Sets the [`language`](SpanContents::language) for syntax highlighting. pub fn with_language(mut self, language: impl Into) -> Self { self.language = Some(language.into()); self