docs: add doc comments, fix rustdoc links, serve docs over HTTP

.config/make/doc.mak

@@ -0,0 +1,24 @@
+## —— Documentation (cargo doc) ----------------------------------------------------------------
+
+DOC_PORT ?= 8765
+DOC_DIR  := target/doc
+
+.PHONY: doc
+doc: ## Generate Rust API documentation (HTML in target/doc)
+	@echo "📚 Building Rust API documentation..."
+	cargo doc --workspace --no-deps
+
+.PHONY: doc-serve
+doc-serve: doc ## Serve docs at http://127.0.0.1:$(DOC_PORT)/ (links work correctly)
+	@echo "📖 Serving docs at http://127.0.0.1:$(DOC_PORT)/ (Ctrl+C to stop)"
+	@cd $(DOC_DIR) && python3 -m http.server $(DOC_PORT)
+
+.PHONY: doc-open
+doc-open: doc ## Generate docs, serve locally, and open in browser (fixes broken file:// links)
+	@echo "📖 Starting local doc server and opening browser..."
+	@if [ ! -d "$(DOC_DIR)" ]; then echo "No $(DOC_DIR); run make doc"; exit 1; fi; \
+	( cd $(DOC_DIR) && nohup python3 -m http.server $(DOC_PORT) </dev/null >/dev/null 2>&1 & ); \
+	sleep 1; \
+	(xdg-open "http://127.0.0.1:$(DOC_PORT)/rustfs/" 2>/dev/null || open "http://127.0.0.1:$(DOC_PORT)/rustfs/" 2>/dev/null) \
+		|| echo "Open http://127.0.0.1:$(DOC_PORT)/rustfs/ in your browser"; \
+	echo "Docs: http://127.0.0.1:$(DOC_PORT)/ — stop server with: pkill -f 'python3 -m http.server $(DOC_PORT)'"

Makefile

@@ -68,6 +68,11 @@ How to use me:
 		make test                                # Run tests
 		make pre-commit                          # Run all pre-commit checks
 
+	📚 Documentation:
+		make doc                                 # Generate Rust API docs (target/doc)
+		make doc-serve                           # Serve docs at http://127.0.0.1:8765/ (links work)
+		make doc-open                            # Generate docs, serve, and open in browser
+
 	🚀 Quick Start:
 		make build                               # Build RustFS binary
 		make docker-dev-local                    # Build development Docker image (local)

crates/appauth/src/lib.rs

@@ -12,4 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Application auth: token encoding/decoding and license parsing.
+
 pub mod token;

crates/appauth/src/token.rs

@@ -26,8 +26,8 @@ pub struct Token {
 }
 
 /// Public key generation Token
-/// [token] Token object
-/// [key] Public key string
+/// * `token` - Token object
+/// * `key` - Public key string
 /// Returns the encrypted string processed by base64
 pub fn gencode(token: &Token, key: &str) -> Result<String> {
     let data = serde_json::to_vec(token)?;
@@ -38,8 +38,8 @@ pub fn gencode(token: &Token, key: &str) -> Result<String> {
 }
 
 /// Private key resolution Token
-/// [token] Encrypted string processed by base64
-/// [key] Private key string
+/// * `token` - Encrypted string processed by base64
+/// * `key` - Private key string
 /// Return to the Token object
 pub fn parse(token: &str, key: &str) -> Result<Token> {
     let encrypted_data = base64_simd::URL_SAFE_NO_PAD

crates/checksums/src/lib.rs

@@ -21,6 +21,8 @@
     rust_2018_idioms
 )]
 
+//! Client and server checksum algorithms (CRC32, CRC32C, CRC64-NVME) and HTTP integration.
+
 use crate::error::UnknownChecksumAlgorithmError;
 
 use bytes::Bytes;

crates/common/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Shared types and utilities: globals, readiness, heal channel, metrics, data usage.
+
 pub mod bucket_stats;
 // pub mod error;
 pub mod data_usage;

crates/config/src/constants/app.rs

@@ -89,25 +89,25 @@ pub const RUSTFS_CA_CERT: &str = "ca.crt";
 /// Default HTTP prefix for rustfs
 /// This is the default HTTP prefix for rustfs.
 /// It is used to identify HTTP URLs.
-/// Default value: http://
+/// Default value: <http://>
 pub const RUSTFS_HTTP_PREFIX: &str = "http://";
 
 /// Default HTTPS prefix for rustfs
 /// This is the default HTTPS prefix for rustfs.
 /// It is used to identify HTTPS URLs.
-/// Default value: https://
+/// Default value: <https://>
 pub const RUSTFS_HTTPS_PREFIX: &str = "https://";
 
 /// Default documentation URL for rustfs
 /// This is the default documentation URL for rustfs.
 /// It is used to provide the documentation of the application.
-/// Default value: https://docs.rustfs.com
+/// Default value: <https://docs.rustfs.com>
 pub const RUSTFS_DOCS_URL: &str = "https://docs.rustfs.com";
 
 /// Default GitHub URL for rustfs
 /// This is the default GitHub URL for rustfs.
 /// It is used to provide the source code of the application.
-/// Default value: https://github.com/rustfs/rustfs
+/// Default value: <https://github.com/rustfs/rustfs>
 pub const RUSTFS_GITHUB_URL: &str = "https://github.com/rustfs/rustfs";
 
 /// Default license for rustfs
@@ -119,7 +119,7 @@ pub const RUSTFS_LICENSE: &str = "Apache-2.0";
 /// Default license URL for rustfs
 /// This is the default license URL for rustfs.
 /// It is used to provide the license URL of the application.
-/// Default value: https://www.apache.org/licenses/LICENSE-2.0
+/// Default value: <https://www.apache.org/licenses/LICENSE-2.0>
 pub const RUSTFS_LICENSE_URL: &str = "https://www.apache.org/licenses/LICENSE-2.0";
 
 /// Environment variable for rustfs address

crates/config/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Server configuration: environment variables, constants, and feature-gated modules.
+
 #[cfg(feature = "constants")]
 pub mod constants;
 #[cfg(feature = "constants")]

crates/credentials/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Credential storage and action credentials (AK/SK, session).
+
 mod constants;
 mod credentials;
 

crates/crypto/src/lib.rs

@@ -13,6 +13,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Encryption, decryption, and JWT encode/decode utilities.
+
 mod encdec;
 mod error;
 mod jwt;

crates/e2e_test/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! End-to-end test suite for RustFS (buckets, objects, versioning, KMS, policy, protocols).
+
 mod reliant;
 
 // Common utilities for all E2E tests

crates/ecstore/src/erasure_coding/erasure.rs

@@ -435,7 +435,7 @@ impl Erasure {
     /// # Arguments
     /// * `reader` - An async reader implementing AsyncRead + Send + Sync + Unpin
     /// * `mut on_block` - Async callback that receives encoded blocks and returns a Result
-    /// * `F` - Callback type: FnMut(Result<Vec<Bytes>, std::io::Error>) -> Future<Output=Result<(), E>> + Send
+    /// * `F` - Callback type: `FnMut(Result<Vec<Bytes>, std::io::Error>) -> Future<Output=Result<(), E>> + Send`
     /// * `Fut` - Future type returned by the callback
     /// * `E` - Error type returned by the callback
     /// * `R` - Reader type implementing AsyncRead + Send + Sync + Unpin

crates/ecstore/src/lib.rs

@@ -13,6 +13,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Erasure-coded storage: buckets, objects, disks, pools, and replication.
+
 extern crate core;
 
 pub mod admin_server_info;

crates/filemeta/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! File and object metadata management, cache, and replication helpers.
+
 mod error;
 mod fileinfo;
 mod filemeta;

crates/heal/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Heal manager, heal channel, and global heal service lifecycle.
+
 mod error;
 pub mod heal;
 

crates/iam/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Identity and Access Management: users, groups, policies, OIDC, and store.
+
 use crate::error::{Error, Result};
 use manager::IamCache;
 use oidc::OidcSys;

crates/lock/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Distributed and local locking for RustFS.
+
 // ============================================================================
 // Core Module Declarations
 // ============================================================================

crates/madmin/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Management API types and helpers (health, metrics, users, heal, trace, etc.).
+
 pub mod group;
 pub mod heal_commands;
 pub mod health;

crates/mcp/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! MCP (Model Context Protocol) server for S3 operations.
+
 pub mod config;
 pub mod s3_client;
 pub mod server;

crates/metrics/src/collectors/mod.rs

@@ -17,10 +17,10 @@
 //! This module provides collectors that convert RustFS data into Prometheus
 //! metrics format. Each collector is responsible for a specific domain:
 //!
-//! - [`cluster`]: Cluster-wide capacity and object statistics
-//! - [`bucket`]: Per-bucket usage and quota metrics
-//! - [`node`]: Per-node disk capacity and health metrics
-//! - [`resource`]: System resource metrics (CPU, memory, uptime)
+//! - **cluster**: Cluster-wide capacity and object statistics
+//! - **bucket**: Per-bucket usage and quota metrics
+//! - **node**: Per-node disk capacity and health metrics
+//! - **resource**: System resource metrics (CPU, memory, uptime)
 //!
 //! # Design Philosophy
 //!

crates/notify/src/rules/pattern_rules.rs

@@ -20,7 +20,7 @@ use rustfs_targets::arn::TargetID;
 use serde::{Deserialize, Serialize};
 
 /// PatternRules - Event rule that maps object name patterns to TargetID collections.
-/// `event.Rules` (map[string]TargetIDSet) in the Go code
+/// `event.Rules` (`map[string]TargetIDSet`) in the Go code
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct PatternRules {
     pub(crate) rules: HashMap<String, TargetIdSet>,

crates/notify/src/rules/rules_map.rs

@@ -18,8 +18,8 @@ use rustfs_s3_common::EventName;
 use rustfs_targets::arn::TargetID;
 use serde::{Deserialize, Serialize};
 
-/// RulesMap - Rule mapping organized by event name。
-/// `event.RulesMap` (map[Name]Rules) in the corresponding Go code
+/// RulesMap - Rule mapping organized by event name.
+/// `event.RulesMap` (`map[Name]Rules`) in the corresponding Go code
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct RulesMap {
     map: HashMap<EventName, PatternRules>,

crates/notify/src/rules/subscriber_snapshot.rs

@@ -84,7 +84,7 @@ where
         self.event_mask == 0 || self.rules.is_empty()
     }
 
-    /// [debug] Assert that `event_mask` is consistent with the event declared in `rules`.
+    /// Debug assertion: `event_mask` is consistent with the event declared in `rules`.
     ///
     /// Constraints:
     /// - only runs in debug builds (release incurs no cost).

crates/notify/src/rules/xml_config.rs

@@ -202,7 +202,7 @@ impl QueueConfig {
 }
 
 /// Corresponding to the `lambda` structure in the Go code.
-/// Used to parse <CloudFunction> ARN from inside the <CloudFunctionConfiguration> tag.
+/// Used to parse `CloudFunction` ARN from inside the `CloudFunctionConfiguration` tag.
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Default)]
 pub struct LambdaConfigDetail {
     #[serde(rename = "CloudFunction")]
@@ -220,7 +220,7 @@ pub struct LambdaConfigDetail {
 }
 
 /// Corresponding to the `topic` structure in the Go code.
-/// Used to parse <Topic> ARN from inside the <TopicConfiguration> tag.
+/// Used to parse `Topic` ARN from inside the `TopicConfiguration` tag.
 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Default)]
 pub struct TopicConfigDetail {
     #[serde(rename = "Topic")]

crates/obs/src/cleaner/core.rs

@@ -31,7 +31,7 @@ use tracing::{debug, error, info};
 
 /// Log-file lifecycle manager.
 ///
-/// Holds all cleanup policy parameters and exposes a single [`cleanup`] method
+/// Holds all cleanup policy parameters and exposes a single [`LogCleaner::cleanup`] method
 /// that performs one full cleanup pass.
 ///
 /// # Thread-safety

crates/obs/src/error.rs

@@ -19,11 +19,9 @@ use tokio::sync::SetError;
 /// Error type for global guard operations
 #[derive(Debug, thiserror::Error)]
 pub enum GlobalError {
-    /// Occurs when attempting to set a global recorder (e.g., via [`crate::Recorder::install_global`] or [`metrics::set_global_recorder`])
+    /// Occurs when attempting to set a global recorder (e.g., when calling [`crate::set_global_guard`]
+    /// or [metrics::set_global_recorder](https://docs.rs/metrics/latest/metrics/fn.set_global_recorder.html))
     /// but a global recorder is already initialized.
-    ///
-    /// [`crate::Recorder::install_global`]: crate::Recorder::install_global
-    /// [`metrics::set_global_recorder`]: https://docs.rs/metrics/latest/metrics/fn.set_global_recorder.html
     #[error("Failed to set a global recorder: {0}")]
     SetRecorder(#[from] metrics::SetRecorderError<crate::Recorder>),
     #[error("Failed to set global guard: {0}")]

crates/obs/src/telemetry/guard.rs

@@ -35,8 +35,8 @@ use pyroscope::pyroscope::PyroscopeAgentRunning;
 /// RAII guard that owns all active OpenTelemetry providers and the
 /// `tracing_appender` worker guard.
 ///
-/// Construct this via the `init_*` functions in [`crate::telemetry`] rather
-/// than directly.  The guard must be kept alive for the entire duration of the
+/// Construct this via the `init_*` functions (e.g. [`crate::init_obs`]) rather than
+/// directly.  The guard must be kept alive for the entire duration of the
 /// application — once dropped, all telemetry pipelines are shut down.
 pub struct OtelGuard {
     /// Optional tracer provider for distributed tracing.

crates/obs/src/telemetry/recorder.rs

@@ -128,7 +128,7 @@ pub struct Recorder {
 }
 
 impl Recorder {
-    /// Creates a new [`Builder`] with a given name for instrumentation.
+    /// Creates a new builder with a given name for instrumentation.
     pub fn builder<S: Into<Cow<'static, str>>>(name: S) -> Builder {
         Builder {
             builder: MeterProviderBuilder::default(),

crates/policy/src/policy/policy.rs

@@ -18,7 +18,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::collections::{HashMap, HashSet};
 /// DEFAULT_VERSION is the default version.
-/// https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_version.html
+/// See <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_version.html>.
 pub const DEFAULT_VERSION: &str = "2012-10-17";
 
 /// check the data is Validator

crates/protocols/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Protocol adapters (FTPS, etc.) and S3 action authorization for protocol sessions.
+
 #![deny(unsafe_code)]
 
 pub mod common;

crates/protos/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Generated gRPC stubs and NodeService client for storage RPC.
+
 #[allow(unsafe_code)]
 mod generated;
 

crates/rio/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! I/O utilities: limit reader, etag reader, hash reader, compression index.
+
 // Default encryption block size - aligned with system default read buffer size (1MB)
 pub const DEFAULT_ENCRYPTION_BLOCK_SIZE: usize = 1024 * 1024;
 

crates/s3select-api/src/lib.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! S3 Select API: object store integration, query server, and execution types.
+
 use datafusion::{common::DataFusionError, sql::sqlparser::parser::ParserError};
 use snafu::{Backtrace, Location, Snafu};
 use std::fmt::Display;

crates/s3select-api/src/query/scheduler.rs

@@ -26,7 +26,7 @@ pub trait Scheduler {
     /// Schedule the provided [`ExecutionPlan`] on this [`Scheduler`].
     ///
     /// Returns a [`ExecutionResults`] that can be used to receive results as they are produced,
-    /// as a [`futures::Stream`] of [`RecordBatch`]
+    /// as a [`futures::Stream`] of `RecordBatch`
     async fn schedule(&self, plan: Arc<dyn ExecutionPlan>, context: Arc<TaskContext>) -> Result<ExecutionResults>;
 }
 

crates/s3select-query/src/data_source/table_source.rs

@@ -102,7 +102,7 @@ impl TableSource for TableSourceAdapter {
         self.table_handle.supports_filters_pushdown(filter)
     }
 
-    /// Called by [`InlineTableScan`]
+    /// Called by `InlineTableScan`
     fn get_logical_plan(&self) -> Option<Cow<'_, LogicalPlan>> {
         Some(Cow::Owned(self.plan.clone()))
     }