chore: fix broken rust documentation
MODIFY
crates/rome_formatter/src/arguments.rs
crates/rome_formatter/src/arguments.rs
@@ -3,8 +3,8 @@ use crate::FormatResult;
use std::ffi::c_void;
use std::marker::PhantomData;
-/// Mono-morphed type to format an object. Used by the [rome_formatter::format], [rome_formatter::format_args], and
-/// [rome_formatter::write] macros.
+/// Mono-morphed type to format an object. Used by the [crate::format!], [crate::format_args!], and
+/// [crate::write!] macros.
///
/// This struct is similar to a dynamic dispatch (using `dyn Format`) because it stores a pointer to the value.
/// However, it doesn't store the pointer to `dyn Format`'s vtable, instead it statically resolves the function

MODIFY
crates/rome_formatter/src/buffer.rs
crates/rome_formatter/src/buffer.rs
@@ -10,10 +10,10 @@ pub trait Buffer {
/// The context used during formatting
type Context;
- /// Writes a [`FormatElement`] into this buffer, returning whether the write succeeded.
+ /// Writes a [crate::FormatElement] into this buffer, returning whether the write succeeded.
///
/// # Errors
- /// This function will return an instance of [`FormatError`] on error.
+ /// This function will return an instance of [crate::FormatError] on error.
///
/// # Examples
///

MODIFY
crates/rome_formatter/src/builders.rs
crates/rome_formatter/src/builders.rs
@@ -1156,7 +1156,7 @@ impl<Context> Format<Context> for ExpandParent {
///
/// The element has no special meaning if used outside of a `Group`. In that case, the content is always emitted.
///
-/// If you're looking for a way to only print something if the `Group` fits on a single line see [if_group_fits_on_single_line].
+/// If you're looking for a way to only print something if the `Group` fits on a single line see [crate::if_group_fits_on_line].
///
/// # Examples
///

MODIFY
crates/rome_formatter/src/format_element.rs
crates/rome_formatter/src/format_element.rs
@@ -37,14 +37,14 @@ pub enum FormatElement {
/// is printed on a single line or multiple lines. See [crate::if_group_breaks] for examples.
ConditionalGroupContent(ConditionalGroupContent),
- /// Concatenates multiple elements together. See [concat_elements] and [join_elements] for examples.
+ /// Concatenates multiple elements together. See [crate::Formatter::join_with] for examples.
List(List),
/// Concatenates multiple elements together with a given separator printed in either
- /// flat or expanded mode to fill the print width. See [fill_elements].
+ /// flat or expanded mode to fill the print width. See [crate::Formatter::fill].
Fill(Fill),
- /// A token that should be printed as is, see [token] for documentation and examples.
+ /// A token that should be printed as is, see [crate::builders::token] for documentation and examples.
Token(Token),
/// Delay the printing of its content until the next line break
@@ -60,7 +60,7 @@ pub enum FormatElement {
/// the parent group to break if this element is at the start of it).
Comment(Box<[FormatElement]>),
- /// A token that tracks tokens/nodes that are printed using [`format_verbatim`](crate::Formatter::format_verbatim) API
+ /// A token that tracks tokens/nodes that are printed as verbatim.
Verbatim(Verbatim),
/// A list of different variants representing the same content. The printer picks the best fitting content.
@@ -156,17 +156,17 @@ impl Debug for FormatElement {
#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub enum LineMode {
- /// See [soft_line_break_or_space] for documentation.
+ /// See [crate::soft_line_break_or_space] for documentation.
SoftOrSpace,
- /// See [soft_line_break] for documentation.
+ /// See [crate::soft_line_break] for documentation.
Soft,
- /// See [hard_line_break] for documentation.
+ /// See [crate::hard_line_break] for documentation.
Hard,
- /// See [empty_line] for documentation.
+ /// See [crate::empty_line] for documentation.
Empty,
}
-/// A token used to gather a list of elements; see [concat_elements] and [join_elements].
+/// A token used to gather a list of elements; see [crate::Formatter::join_with].
#[derive(Clone, Default, Eq, PartialEq)]
pub struct List {
content: Vec<FormatElement>,
@@ -381,7 +381,7 @@ impl ConditionalGroupContent {
}
}
-/// See [token] for documentation
+/// See [crate::builders::token] for documentation
#[derive(Eq, Clone)]
pub enum Token {
/// Token constructed by the formatter from a static string
@@ -499,7 +499,7 @@ impl FormatElement {
/// Returns true if this [FormatElement] is guaranteed to break across multiple lines by the printer.
/// This is the case if this format element recursively contains a:
- /// * [empty_line] or [hard_line_break]
+ /// * [crate::empty_line] or [crate::hard_line_break]
/// * A token containing '\n'
///
/// Use this with caution, this is only a heuristic and the printer may print the element over multiple

MODIFY
crates/rome_formatter/src/format_extensions.rs
crates/rome_formatter/src/format_extensions.rs
@@ -6,14 +6,11 @@ use std::ops::Deref;
use crate::Buffer;
/// Utility trait used to simplify the formatting of optional objects that are formattable.
-///
-/// In order to take advantage of all the functions, you only need to implement the [FormatOptionalTokenAndNode::with_or]
-/// function.
pub trait FormatOptional<Context> {
type Target: Format<Context>;
/// This function tries to format an optional object. If the object is [None]
- /// an [empty token](crate::FormatElement::Empty) is created. If exists, the utility
+ /// nothing is written in the buffer. If exists, the utility
/// formats the object and passes it to the closure.
///
/// ## Examples

MODIFY
crates/rome_formatter/src/formatter.rs
crates/rome_formatter/src/formatter.rs
@@ -89,11 +89,11 @@ impl<'buf, Context> Formatter<'buf, Context> {
JoinBuilder::with_separator(self, joiner)
}
- /// Specialized version of [join_with] for joining SyntaxNodes separated by a space, soft
+ /// Specialized version of [crate::Formatter::join_with] for joining SyntaxNodes separated by a space, soft
/// line break or empty line depending on the input file.
///
/// This functions inspects the input source and separates consecutive elements with either
- /// a [soft_line_break_or_space] or [empty_line] depending on how many line breaks were
+ /// a [crate::soft_line_break_or_space] or [crate::empty_line] depending on how many line breaks were
/// separating the elements in the original file.
pub fn join_nodes_with_soft_line<'a>(
&'a mut self,
@@ -101,17 +101,17 @@ impl<'buf, Context> Formatter<'buf, Context> {
JoinNodesBuilder::new(soft_line_break_or_space(), self)
}
- /// Specialized version of [join_with] for joining SyntaxNodes separated by one or more
+ /// Specialized version of [crate::Formatter::join_with] for joining SyntaxNodes separated by one or more
/// line breaks depending on the input file.
///
/// This functions inspects the input source and separates consecutive elements with either
- /// a [hard_line_break] or [empty_line] depending on how many line breaks were separating the
+ /// a [crate::hard_line_break] or [crate::empty_line] depending on how many line breaks were separating the
/// elements in the original file.
pub fn join_nodes_with_hardline<'a>(&'a mut self) -> JoinNodesBuilder<'a, 'buf, Line, Context> {
JoinNodesBuilder::new(hard_line_break(), self)
}
- /// Concatenates a list of [Format] objects with spaces and line breaks to fit
+ /// Concatenates a list of [crate::Format] objects with spaces and line breaks to fit
/// them on as few lines as possible. Each element introduces a conceptual group. The printer
/// first tries to print the item in flat mode but then prints it in expanded mode if it doesn't fit.
///

MODIFY
crates/rome_formatter/src/group_id.rs
crates/rome_formatter/src/group_id.rs
@@ -25,7 +25,7 @@ impl std::fmt::Debug for DebugGroupId {
/// Unique identification for a group.
///
-/// See [crate::Formater::group_id] on how to get a unique id.
+/// See [crate::Formatter::group_id] on how to get a unique id.
#[repr(transparent)]
#[derive(Clone, Copy, Eq, PartialEq, Hash)]
pub struct ReleaseGroupId {

MODIFY
crates/rome_formatter/src/lib.rs
crates/rome_formatter/src/lib.rs
//! * [`format_args!`]: Concatenates a sequence of Format objects.
//! * [`write!`]: Writes a sequence of formatable objects into an output buffer.
+#![deny(rustdoc::broken_intra_doc_links)]
+
mod arguments;
mod buffer;
mod builders;
@@ -438,7 +440,7 @@ impl<Context> Format<Context> for () {
}
}
-/// Rule that knows how to format an object of type [T].
+/// Rule that knows how to format an object of type `T`.
///
/// Implementing [Format] on the object itself is preferred over implementing [FormatRule] but
/// this isn't possible inside of a dependent crate for external type.
@@ -454,7 +456,7 @@ pub trait FormatRule<T> {
fn fmt(&self, item: &T, f: &mut Formatter<Self::Context>) -> FormatResult<()>;
}
-/// Rule that supports customizing how it formats an object of type [T].
+/// Rule that supports customizing how it formats an object of type `T`.
pub trait FormatRuleWithOptions<T>: FormatRule<T> {
type Options;
@@ -475,16 +477,15 @@ pub trait FormatRuleWithOptions<T>: FormatRule<T> {
/// itself but the language specific crate implements `AsFormat` and `IntoFormat` for it and the returned [Format]
/// implement [FormatWithRule].
///
-/// ```
+/// ```ignore
/// use rome_formatter::prelude::*;
/// use rome_formatter::{format, Formatted, FormatWithRule};
/// use rome_rowan::{Language, SyntaxNode};
/// fn format_node<L: Language, F: FormatWithRule<SimpleFormatContext, Item=SyntaxNode<L>>>(node: F) -> FormatResult<Formatted> {
/// let formatted = format!(SimpleFormatContext::default(), [node]);
-/// let _syntax = node.item();
-///
+/// let syntax = node.item();
/// // Do something with syntax
-/// formatted
+/// formatted;
/// }
/// ```
pub trait FormatWithRule<Context>: Format<Context> {
@@ -616,7 +617,7 @@ where
/// let mut state = FormatState::new(SimpleFormatContext::default());
/// let mut buffer = VecBuffer::new(&mut state);
///
-/// write(&mut buffer, format_args!(token("Hello World"))).unwrap();
+/// write!(&mut buffer, [format_args!(token("Hello World"))]).unwrap();
///
/// let formatted = Formatted::new(buffer.into_element(), PrinterOptions::default());
///
@@ -660,7 +661,7 @@ pub fn write<Context>(
/// use rome_formatter::prelude::*;
/// use rome_formatter::{format, format_args};
///
-/// let formatted = format(SimpleFormatContext::default(), format_args!(token("test"))).unwrap();
+/// let formatted = format!(SimpleFormatContext::default(), [&format_args!(token("test"))]).unwrap();
/// assert_eq!("test", formatted.print().as_code());
/// ```
///
@@ -1089,9 +1090,9 @@ impl<L: Language, Context> Format<Context> for SyntaxTriviaPieceComments<L> {
/// This structure stores the state that is relevant for the formatting of the whole document.
///
-/// This structure is different from [`Formatter`] in that the formatting infrastructure
-/// creates a new [`Formatter`] for every [`write`] call, whereas this structure stays alive
-/// for the whole process of formatting a root with [`format`].
+/// This structure is different from [crate::Formatter] in that the formatting infrastructure
+/// creates a new [crate::Formatter] for every [crate::write!] call, whereas this structure stays alive
+/// for the whole process of formatting a root with [crate::format!].
#[derive(Default)]
pub struct FormatState<Context> {
context: Context,

MODIFY
crates/rome_formatter/src/macros.rs
crates/rome_formatter/src/macros.rs
/// Constructs the parameters for other formatting macros.
///
-/// This macro functions by taking a list of objects implementing [Format]. It canonicalize the
+/// This macro functions by taking a list of objects implementing [crate::Format]. It canonicalize the
/// arguments into a single type.
///
-/// This macro produces a value of type [`Arguments`]. This value can be passed to
-/// the macros within [`rome_formatter`]. All other formatting macros ([`format!`],
-/// [`write!`]) are proxied through this one. This macro avoids heap allocations.
+/// This macro produces a value of type [crate::Arguments]. This value can be passed to
+/// the macros within [crate]. All other formatting macros ([`format!`](crate::format!),
+/// [`write!`](crate::write!)) are proxied through this one. This macro avoids heap allocations.
///
/// You can use the [`Arguments`] value that `format_args!` returns in `Format` contexts
/// as seen below.
///
/// [`Format`]: crate::Format
/// [`Arguments`]: crate::Arguments
-/// [`format!`]: crate::format
-/// [`write!`]: crate::write
#[macro_export]
macro_rules! format_args {
($($value:expr),+ $(,)?) => {
@@ -40,7 +38,7 @@ macro_rules! format_args {
///
/// This macro accepts a 'buffer' and a list of format arguments. Each argument will be formatted
/// and the result will be passed to the buffer. The writer may be any value with a `write_fmt` method;
-/// generally this comes from an implementation of the [`Buffer`] trait.
+/// generally this comes from an implementation of the [crate::Buffer] trait.
///
/// # Examples
///
@@ -111,8 +109,8 @@ macro_rules! dbg_write {
/// Creates the Format IR for a value.
///
-/// The first argument `format!` receives is the [FormatContext] that specify how elements must be formatted.
-/// Additional parameters passed get formatted by using their [Format] implementation.
+/// The first argument `format!` receives is the [crate::FormatContext] that specify how elements must be formatted.
+/// Additional parameters passed get formatted by using their [crate::Format] implementation.
///
///
/// ## Examples

MODIFY
crates/rome_formatter/src/printer/printer_options/mod.rs
crates/rome_formatter/src/printer/printer_options/mod.rs
use crate::{IndentStyle, LineWidth};
-/// Options that affect how the [Printer] prints the format tokens
+/// Options that affect how the [crate::Printer] prints the format tokens
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PrinterOptions {
/// Width of a single tab character (does it equal 2, 4, ... spaces?)

MODIFY
crates/rome_rowan/src/lib.rs
crates/rome_rowan/src/lib.rs
// missing_docs,
)]
#![deny(unsafe_code)]
+#![deny(rustdoc::broken_intra_doc_links)]
#[doc(hidden)]
pub mod macros;

MODIFY
crates/rome_rowan/src/syntax/trivia.rs
crates/rome_rowan/src/syntax/trivia.rs
@@ -201,7 +201,7 @@ impl<L: Language> SyntaxTriviaPieceSkipped<L> {
///
/// For example:
///
-/// ```ignore
+/// ```no_test
/// builder.token_with_trivia(
/// RawSyntaxKind(1),
/// "\n\t /**/let \t\t",
@@ -209,10 +209,10 @@ impl<L: Language> SyntaxTriviaPieceSkipped<L> {
/// &[TriviaPiece::whitespace(3)],
/// );
/// });
-///
+/// ```
/// This token has two pieces in the leading trivia, and one piece at the trailing trivia. Each
/// piece is defined by the [TriviaPiece]; its content is irrelevant.
-/// ```
+///
#[derive(Clone)]
pub struct SyntaxTriviaPiece<L: Language> {
raw: cursor::SyntaxTrivia,
@@ -265,7 +265,7 @@ impl<L: Language> SyntaxTriviaPiece<L> {
&txt[start.into()..end.into()]
}
- /// Returns the associated text length just for this trivia piece. This is different from [SyntaxTrivia::text_len()],
+ /// Returns the associated text length just for this trivia piece. This is different from `SyntaxTrivia::len()`,
/// which returns the text length of the whole trivia.
///
/// ```

MODIFY
crates/rome_rowan/src/syntax_factory/raw_syntax.rs
crates/rome_rowan/src/syntax_factory/raw_syntax.rs
@@ -2,10 +2,10 @@ use crate::green::GreenElement;
use crate::{GreenNode, GreenToken, NodeOrToken, SyntaxKind};
use std::marker::PhantomData;
-/// New-type wrapper around a [GreenNode].
+/// New-type wrapper around a `GreenNode`.
///
-/// Allows third-party crates to access limited information about a [GreenNode] or construct
-/// a [GreenNode] in a limited places.
+/// Allows third-party crates to access limited information about a `GreenNode` or construct
+/// a `GreenNode` in a limited places.
#[derive(Debug)]
pub struct RawSyntaxNode<K: SyntaxKind> {
raw: GreenNode,
@@ -53,7 +53,7 @@ impl<K: SyntaxKind> From<GreenNode> for RawSyntaxNode<K> {
}
}
-/// New-type wrapper around a [GreenToken]. Allows third-party crates to access limited information
+/// New-type wrapper around a `GreenToken`. Allows third-party crates to access limited information
/// on not yet fully constructed nodes.
#[derive(Debug)]
pub struct RawSyntaxToken<K: SyntaxKind> {
@@ -107,7 +107,7 @@ impl<K: SyntaxKind> From<GreenElement> for RawSyntaxElement<K> {
}
}
-/// New-type wrapper to a reference of a [GreenNode].
+/// New-type wrapper to a reference of a `GreenNode`.
#[derive(Debug)]
pub struct RawSyntaxNodeRef<'a, K: SyntaxKind> {
raw: &'a GreenNode,
@@ -131,7 +131,7 @@ impl<'a, K: SyntaxKind> From<&'a GreenNode> for RawSyntaxNodeRef<'a, K> {
}
}
-/// New-type wrapper to a reference of a [GreenToken]
+/// New-type wrapper to a reference of a `GreenToken`
#[derive(Debug)]
pub struct RawSyntaxTokenRef<'a, K: SyntaxKind> {
raw: &'a GreenToken,

chore: fix broken rust documentation (#2805)