ci: add documentation check on CI (#2806)

.cargo/config.toml

@@ -3,6 +3,7 @@ lint = "clippy --workspace --all-targets --verbose -- --deny warnings"
 format = "fmt --all --verbose"
 codegen = "run -p xtask_codegen --"
 lintdoc = "run -p xtask_lintdoc --"
+documentation = "doc -p rome_formatter -p rome_control_flow -p rome_analyze -p rome_*_syntax -p rome_*_factory -p rome_diagnostics -p rome_service -p rome_cli -p rome_console --no-deps"
 bench_parser = "run -p xtask_bench --release -- --feature parser"
 bench_formatter = "run -p xtask_bench --release -- --feature formatter"
 bench_analyzer = "run -p xtask_bench --release -- --feature analyzer"

.github/workflows/main.yml

@@ -89,6 +89,23 @@ jobs:
       - name: Clean cache
         run: cargo install cargo-cache --no-default-features --features ci-autoclean && cargo-cache
 
+  documentation:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Install toolchain
+        run: rustup show
+      - name: Cache
+        uses: Swatinem/rust-cache@v1
+      - name: Compile for tests
+        uses: actions-rs/cargo@v1
+      - name: Run doc command
+        uses: actions-rs/cargo@v1
+        with:
+          command: documentation
+
   coverage:
     name: Test262 Coverage
     runs-on: ${{ matrix.os }}

.github/workflows/pull_request.yml

@@ -81,6 +81,24 @@ jobs:
           command: test
           args: --workspace --verbose
 
+  documentation:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Install toolchain
+        run: rustup show
+      - name: Cache
+        uses: Swatinem/rust-cache@v1
+      - name: Compile for tests
+        uses: actions-rs/cargo@v1
+      - name: Run doc command
+        uses: actions-rs/cargo@v1
+        with:
+          command: documentation
+
+
   codegen:
     name: Codegen
     runs-on: ubuntu-latest

crates/rome_analyze/src/lib.rs

@@ -1,3 +1,5 @@
+#![deny(rustdoc::broken_intra_doc_links)]
+
 use std::ops;
 
 mod categories;
@@ -76,7 +78,7 @@ impl AnalysisFilter<'_> {
 }
 
 /// Utility type to be used as a default value for the `B` generic type on
-/// [analyze] when the provided callback never breaks
+/// `analyze` when the provided callback never breaks
 ///
 /// This should eventually get replaced with the `!` type when it gets stabilized
 pub enum Never {}
@@ -91,7 +93,7 @@ pub enum Never {}
 /// In practice it's not really a `loop` but a `for` because it's iterating on
 /// all nodes in the syntax tree, so when it reaches the end of the iterator
 /// the loop will exit but without producing a value of type `B`: for this
-/// reason the [analyze] function returns an `Option<B>` that's set to
+/// reason the `analyze` function returns an `Option<B>` that's set to
 /// `Some(B)` if the callback did break, and `None` if the analysis reached the
 /// end of the file.
 ///

crates/rome_analyze/src/signals.rs

@@ -14,15 +14,15 @@ use crate::{
     rule::Rule,
 };
 
-/// Event raised by the analyzer when a [Rule](crate::registry::Rule)
+/// Event raised by the analyzer when a [Rule](crate::Rule)
 /// emits a diagnostic, a code action, or both
 pub trait AnalyzerSignal<L: Language> {
     fn diagnostic(&self) -> Option<Diagnostic>;
     fn action(&self) -> Option<AnalyzerAction<L>>;
 }
 
-/// Code Action object returned by the analyzer, generated from a [RuleAction](crate::registry::RuleAction)
-/// with additional informations about the rule injected by the analyzer
+/// Code Action object returned by the analyzer, generated from a [crate::RuleAction]
+/// with additional information about the rule injected by the analyzer
 ///
 /// This struct can be converted into a [CodeSuggestion] and injected into
 /// a diagnostic emitted by the same signal

crates/rome_analyze/src/visitor.rs

@@ -25,7 +25,7 @@ impl<'a, L: Language, B> VisitorContext<'a, L, B> {
 
 /// Visitors are the main building blocks of the analyzer: they receive syntax
 /// [WalkEvent]s, process these events to build secondary data structures from
-/// the syntax tree, and emit rule query matches through the [RuleRegistry]
+/// the syntax tree, and emit rule query matches through the [crate::RuleRegistry]
 pub trait Visitor<B> {
     type Language: Language;
 

crates/rome_console/src/codespan/mod.rs

@@ -1,4 +1,4 @@
-//! This module is a fork of https://github.com/brendanzab/codespan
+//! This module is a fork of <https://github.com/brendanzab/codespan>
 //! adapted to use the `rome_console` markup for formatting
 use std::collections::BTreeMap;
 use std::io;

crates/rome_console/src/lib.rs

@@ -27,7 +27,7 @@ pub enum LogLevel {
 /// Generic abstraction over printing markup and diagnostics to an output,
 /// which can be a terminal, a file, a memory buffer ...
 pub trait Console: Send + Sync + RefUnwindSafe {
-    /// Prints a message (formatted using [markup]) to the console
+    /// Prints a message (formatted using [markup!]) to the console
     fn print(&mut self, level: LogLevel, args: Markup);
 }
 

crates/rome_control_flow/src/lib.rs

@@ -1,3 +1,5 @@
+#![deny(rustdoc::broken_intra_doc_links)]
+
 use std::{
     collections::HashMap,
     fmt::{self, Display, Formatter},

crates/rome_service/src/workspace.rs

@@ -30,7 +30,7 @@
 //!
 //! # Implementations
 //!
-//! Currently the [Workspace] trait is implemented for a single [server::WorkspaceServer]
+//! Currently the [Workspace] trait is implemented for a single `WorkspaceServer`
 //! type. However it is eventually intended to also be implemented for a
 //! potential `WorkspaceClient` type and to operate on a remote workspace
 //! server through a transport layer. This would allow the CLI and Language

xtask/codegen/src/generate_macros.rs

@@ -38,8 +38,8 @@ pub fn generate_macros(ast: &AstSrc, language_kind: LanguageKind) -> Result<Stri
     let ast = quote! {
         /// Reconstruct an AstNode from a SyntaxNode
         ///
-        /// This macros performs a match over the [kind](SyntaxNode::kind)
-        /// of the provided [SyntaxNode] and constructs the appropriate
+        /// This macros performs a match over the [kind](rome_rowan::SyntaxNode::kind)
+        /// of the provided [rome_rowan::SyntaxNode] and constructs the appropriate
         /// AstNode type for it, then execute the provided expression over it.
         ///
         /// # Examples