docs: add doc comments, fix rustdoc links, serve docs over HTTP#2
Open
andybrown668 wants to merge 1 commit intomainfrom
Open
docs: add doc comments, fix rustdoc links, serve docs over HTTP#2andybrown668 wants to merge 1 commit intomainfrom
andybrown668 wants to merge 1 commit intomainfrom
Conversation
RustFS and crates: - Add module-level (//!) and crate-level doc comments across rustfs binary, storage, admin, server, and all workspace library crates. - Fix make doc warnings: rustdoc bare URLs, unclosed HTML, broken intra-doc links in config, utils, obs, policy, appauth, checksums, ecstore, notify, metrics, s3select-*, rustfs. Documentation and Make: - Add .config/make/doc.mak with doc, doc-serve, doc-open targets. - doc-open now serves target/doc over HTTP (port 8765) and opens the browser so cross-crate and static file links work (fixes broken file:// links). - doc-serve: serve docs in foreground. Update doc/development.md and Makefile help. Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Adds/updates Rustdoc documentation across the RustFS workspace and introduces Make targets to generate and serve docs over HTTP so cross-crate/static links work reliably.
Changes:
- Add crate/module-level doc comments (
//!) acrossrustfsand workspace crates; clean up various Rustdoc link/format warnings. - Add
doc,doc-serve, anddoc-openMake targets (via.config/make/doc.mak) and document them inMakefilehelp +doc/development.md. - Minor docstring formatting/link fixes in several existing modules.
Reviewed changes
Copilot reviewed 132 out of 132 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| rustfs/src/version.rs | Add module doc comment. |
| rustfs/src/update.rs | Add module doc comment. |
| rustfs/src/storage/tonic_service.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/tagging.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/select.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/restore.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/response.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/replication.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/object_lock.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/multipart.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/mod.rs | Add/adjust module docs for S3 API facade. |
| rustfs/src/storage/s3_api/encryption.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/common.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/bucket.rs | Add module doc comment. |
| rustfs/src/storage/s3_api/acl.rs | Add module doc comment. |
| rustfs/src/storage/rpc/node_service.rs | Add module doc comment. |
| rustfs/src/storage/rpc/mod.rs | Add module doc comment. |
| rustfs/src/storage/rpc/metrics.rs | Add module doc comment. |
| rustfs/src/storage/rpc/lock.rs | Add module doc comment. |
| rustfs/src/storage/rpc/health.rs | Add module doc comment. |
| rustfs/src/storage/rpc/disk.rs | Add module doc comment. |
| rustfs/src/storage/rpc/bucket.rs | Add module doc comment. |
| rustfs/src/storage/readers.rs | Add module doc comment. |
| rustfs/src/storage/options.rs | Add module doc comment. |
| rustfs/src/storage/mod.rs | Add module doc comment + short overview. |
| rustfs/src/storage/helper.rs | Add module doc comment. |
| rustfs/src/storage/head_prefix.rs | Add module doc comment. |
| rustfs/src/storage/entity.rs | Add module doc comment. |
| rustfs/src/storage/ecfs_extend.rs | Add module doc comment; small doc formatting tweak. |
| rustfs/src/storage/ecfs.rs | Add module doc comment. |
| rustfs/src/storage/access.rs | Add module doc comment. |
| rustfs/src/server/service_state.rs | Add module doc comment. |
| rustfs/src/server/runtime.rs | Add module doc comment. |
| rustfs/src/server/readiness.rs | Add module doc comment. |
| rustfs/src/server/prefix.rs | Add module doc comment. |
| rustfs/src/server/mod.rs | Add module doc comment + short overview. |
| rustfs/src/server/layer.rs | Add module doc comment. |
| rustfs/src/server/hybrid.rs | Add module doc comment. |
| rustfs/src/server/http.rs | Add module doc comment; fix a rustdoc link target. |
| rustfs/src/server/event.rs | Add module doc comment. |
| rustfs/src/server/cert.rs | Add module doc comment. |
| rustfs/src/server/audit.rs | Add module doc comment. |
| rustfs/src/protocols/mod.rs | Add module doc comment. |
| rustfs/src/protocols/client.rs | Add module doc comment. |
| rustfs/src/profiling/allocator.rs | Add module doc comment. |
| rustfs/src/profiling.rs | Add module doc comment. |
| rustfs/src/main.rs | Add crate docs + function doc comments for entrypoints. |
| rustfs/src/license.rs | Add module doc comment. |
| rustfs/src/init.rs | Add module doc comment. |
| rustfs/src/error.rs | Add module doc comment. |
| rustfs/src/config/mod.rs | Add module doc comment. |
| rustfs/src/auth.rs | Add module doc comment. |
| rustfs/src/app/mod.rs | Expand/refresh module docs. |
| rustfs/src/admin/utils.rs | Add module doc comment. |
| rustfs/src/admin/rpc.rs | Add module doc comment. |
| rustfs/src/admin/router.rs | Add module doc comment. |
| rustfs/src/admin/mod.rs | Add module doc comment + short overview. |
| rustfs/src/admin/handlers/user_policy_binding.rs | Add module doc comment. |
| rustfs/src/admin/handlers/user_lifecycle.rs | Add module doc comment. |
| rustfs/src/admin/handlers/user_iam.rs | Add module doc comment. |
| rustfs/src/admin/handlers/user.rs | Add module doc comment. |
| rustfs/src/admin/handlers/trace.rs | Add module doc comment. |
| rustfs/src/admin/handlers/tier.rs | Add module doc comment. |
| rustfs/src/admin/handlers/system.rs | Add module doc comment. |
| rustfs/src/admin/handlers/sts.rs | Add module doc comment. |
| rustfs/src/admin/handlers/service_account.rs | Add module doc comment. |
| rustfs/src/admin/handlers/replication.rs | Add module doc comment. |
| rustfs/src/admin/handlers/rebalance.rs | Add module doc comment. |
| rustfs/src/admin/handlers/profile_admin.rs | Add module doc comment. |
| rustfs/src/admin/handlers/profile.rs | Add module doc comment. |
| rustfs/src/admin/handlers/pools.rs | Add module doc comment. |
| rustfs/src/admin/handlers/policies.rs | Add module doc comment. |
| rustfs/src/admin/handlers/oidc.rs | Add module doc comment. |
| rustfs/src/admin/handlers/mod.rs | Add module doc comment. |
| rustfs/src/admin/handlers/metrics.rs | Add module doc comment. |
| rustfs/src/admin/handlers/is_admin.rs | Add module doc comment. |
| rustfs/src/admin/handlers/health.rs | Add module doc comment. |
| rustfs/src/admin/handlers/heal.rs | Add module doc comment. |
| rustfs/src/admin/handlers/group.rs | Add module doc comment. |
| rustfs/src/admin/handlers/event.rs | Add module doc comment. |
| rustfs/src/admin/handlers/bucket_meta.rs | Add module doc comment. |
| rustfs/src/admin/handlers/account_info.rs | Add module doc comment. |
| rustfs/src/admin/console.rs | Add module doc comment. |
| rustfs/src/admin/auth.rs | Add module doc comment. |
| doc/development.md | Add development guide including doc targets. |
| crates/zip/src/lib.rs | Add crate doc comment. |
| crates/workers/src/lib.rs | Add crate doc comment. |
| crates/utils/src/lib.rs | Add crate doc comment. |
| crates/utils/src/hash.rs | Doc formatting tweak. |
| crates/utils/src/envs.rs | Doc formatting tweak. |
| crates/utils/src/compress.rs | Doc formatting tweaks. |
| crates/utils/src/certs.rs | Doc formatting tweaks. |
| crates/trusted-proxies/src/lib.rs | Add crate doc comment. |
| crates/targets/src/lib.rs | Add crate doc comment. |
| crates/signer/src/lib.rs | Add crate doc comment. |
| crates/scanner/src/lib.rs | Add crate doc comment. |
| crates/s3select-query/src/lib.rs | Add crate doc comment. |
| crates/s3select-query/src/data_source/table_source.rs | Doc link formatting tweak. |
| crates/s3select-api/src/query/scheduler.rs | Doc link formatting tweak. |
| crates/s3select-api/src/lib.rs | Add crate doc comment. |
| crates/rio/src/lib.rs | Add crate doc comment. |
| crates/protos/src/lib.rs | Add crate doc comment. |
| crates/protocols/src/lib.rs | Add crate doc comment. |
| crates/policy/src/policy/policy.rs | Replace bare URL with angle-bracket link. |
| crates/obs/src/telemetry/recorder.rs | Doc wording tweak to avoid broken link. |
| crates/obs/src/telemetry/guard.rs | Doc link update to a valid public API item. |
| crates/obs/src/error.rs | Doc link formatting and external link cleanup. |
| crates/obs/src/cleaner/core.rs | Doc link fix to concrete method path. |
| crates/notify/src/rules/xml_config.rs | Doc formatting tweaks for tags/type names. |
| crates/notify/src/rules/subscriber_snapshot.rs | Doc wording tweak. |
| crates/notify/src/rules/rules_map.rs | Doc punctuation/formatting fixes. |
| crates/notify/src/rules/pattern_rules.rs | Doc formatting fix. |
| crates/metrics/src/collectors/mod.rs | Doc wording tweak (avoid linking to private modules). |
| crates/mcp/src/lib.rs | Add crate doc comment. |
| crates/madmin/src/lib.rs | Add crate doc comment. |
| crates/lock/src/lib.rs | Add crate doc comment. |
| crates/iam/src/lib.rs | Add crate doc comment. |
| crates/heal/src/lib.rs | Add crate doc comment. |
| crates/filemeta/src/lib.rs | Add crate doc comment. |
| crates/ecstore/src/lib.rs | Add crate doc comment. |
| crates/ecstore/src/erasure_coding/erasure.rs | Doc formatting tweak for callback type. |
| crates/e2e_test/src/lib.rs | Add crate doc comment. |
| crates/crypto/src/lib.rs | Add crate doc comment. |
| crates/credentials/src/lib.rs | Add crate doc comment. |
| crates/config/src/lib.rs | Add crate doc comment. |
| crates/config/src/constants/app.rs | Convert bare URLs to angle-bracket links in docs. |
| crates/common/src/lib.rs | Add crate doc comment. |
| crates/checksums/src/lib.rs | Add crate doc comment. |
| crates/appauth/src/token.rs | Doc formatting tweaks for params. |
| crates/appauth/src/lib.rs | Add crate doc comment. |
| Makefile | Extend help text with doc targets. |
| .config/make/doc.mak | Add doc, doc-serve, doc-open targets. |
Comment on lines
+14
to
+20
| @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 & ); \ |
There was a problem hiding this comment.
python3 -m http.server binds to 0.0.0.0 by default, but the target description/echo text says it serves at 127.0.0.1. To avoid exposing the docs server on all interfaces, pass an explicit bind address (and keep the printed URL consistent).
Suggested change
| @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 & ); \ | |
| @cd $(DOC_DIR) && python3 -m http.server $(DOC_PORT) --bind 127.0.0.1 | |
| .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) --bind 127.0.0.1 </dev/null >/dev/null 2>&1 & ); \ |
Comment on lines
+20
to
+24
| ( 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)'" |
There was a problem hiding this comment.
doc-open backgrounds a server and suggests stopping it via pkill -f ..., which can accidentally kill unrelated python3 -m http.server processes on the same port/pattern. Consider capturing and printing the spawned server PID (or writing a PID file) so users can stop exactly the server started by this target, and surface bind/startup failures instead of redirecting all output to /dev/null.
Suggested change
| ( 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)'" | |
| ( cd $(DOC_DIR) && \ | |
| nohup python3 -m http.server $(DOC_PORT) </dev/null >/dev/null 2>doc-open-server.err & \ | |
| echo $$! > .doc-open.pid ); \ | |
| sleep 1; \ | |
| SERVER_PID=$$(cat $(DOC_DIR)/.doc-open.pid 2>/dev/null || echo ""); \ | |
| if [ -z "$$SERVER_PID" ]; then \ | |
| echo "Failed to start docs server. See $(DOC_DIR)/doc-open-server.err for details."; \ | |
| exit 1; \ | |
| fi; \ | |
| (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)/ — server PID: $$SERVER_PID — stop server with: kill $$SERVER_PID" |
Comment on lines
89
to
99
| /// 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://"; |
There was a problem hiding this comment.
For these prefix constants, rendering http:// / https:// as Markdown autolinks (<http://>, <https://>) is misleading (and may still produce invalid/odd links in rustdoc). Prefer code formatting (e.g. backticks) to show they are string prefixes, not clickable URLs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Type of Change
Related Issues
N/A
Summary of Changes
Add crate/module doc comments, fix rustdoc links, and serve docs over HTTP.
RustFS and crates:
//!) and crate-level doc comments across rustfs binary, storage, admin, server, and all workspace library crates.make docwarnings: rustdoc bare URLs, unclosed HTML, broken intra-doc links in config, utils, obs, policy, appauth, checksums, ecstore, notify, metrics, s3select-*, rustfs.Documentation and Make:
.config/make/doc.makwithdoc,doc-serve,doc-opentargets.doc-openservestarget/docover HTTP (port 8765) and opens the browser so cross-crate and static file links work (fixes brokenfile://links).doc-serve: serve docs in foreground. Updatedoc/development.mdand Makefile help.Checklist
make pre-commitImpact
Additional Notes
Single-commit PR split from
andy/documentationfor easier review. Depends on in-repo docs (e.g.doc/development.md); can be reviewed after or in parallel with the docs-in-repo PR.Verification:
make pre-commitandmake doc(optional:make doc-opento test served docs).Thank you for your contribution! Please ensure your PR follows the community standards (CODE_OF_CONDUCT.md) and sign the CLA if this is your first contribution.