Skip to content

Commit

Permalink
docs: Fix some broken links and missing backticks. (#399)
Browse files Browse the repository at this point in the history
  • Loading branch information
waywardmonkeys authored Sep 25, 2024
1 parent 215f9aa commit d60c8f1
Show file tree
Hide file tree
Showing 6 changed files with 23 additions and 22 deletions.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion src/handlers/graphical.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
24 changes: 12 additions & 12 deletions src/highlighters/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -46,22 +46,22 @@ 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]
/// regions.
fn highlight_line<'s>(&mut self, line: &'s str) -> Vec<Styled<&'s str>>;
}

/// 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<dyn Highlighter + Send + Sync>);
Expand Down
8 changes: 4 additions & 4 deletions src/highlighters/syntect.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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() {
Expand All @@ -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,
Expand Down Expand Up @@ -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 {
Expand Down
4 changes: 2 additions & 2 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/protocol.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String>) -> Self {
self.language = Some(language.into());
self
Expand Down

0 comments on commit d60c8f1

Please sign in to comment.