Improve httpgenerator-core rustdoc

[christianhelle]

httpgenerator-core is the public library surface shown on docs.rs, but many exported items lacked rustdoc. This change makes the crate documentation more useful for downstream users by explaining the main generation flow, normalized model, OpenAPI helpers, and public utility APIs.

Summary

• Adds crate-level and module-level rustdoc that guides users through generation, normalization, and OpenAPI loading.
• Documents public structs, fields, enum variants, functions, and error variants across the core, normalized, OpenAPI, and helper APIs.
• Adds practical rustdoc examples, using compile-tested examples where possible and no_run for file or URL loading flows.
• Enables #![warn(missing_docs)] so future public API documentation gaps are visible without blocking development.
• Fixes intra-doc links so docs build cleanly under rustdoc warnings.

Validation

• RUSTDOCFLAGS="-D warnings" cargo doc -p httpgenerator-core --no-deps
• cargo test --workspace

Summary by CodeRabbit

Release Notes

• Documentation

  • Added comprehensive API documentation and usage examples throughout the library for improved developer experience.

• New Features

  • Enhanced OpenApiInspection to include statistics for better document analysis.
  • Improved public API exports for enhanced convenience and discoverability.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e4f5b4c2-dfe9-4989-933c-15535cfcfc9f

📥 Commits

Reviewing files that changed from the base of the PR and between 65ed1aa and 96ee192.

📒 Files selected for processing (30)

• src/rust/core/src/base_url.rs
• src/rust/core/src/file_naming.rs
• src/rust/core/src/generator/mod.rs
• src/rust/core/src/generator/modes.rs
• src/rust/core/src/lib.rs
• src/rust/core/src/model/mod.rs
• src/rust/core/src/model/output_type.rs
• src/rust/core/src/model/result.rs
• src/rust/core/src/model/settings.rs
• src/rust/core/src/normalized/document.rs
• src/rust/core/src/normalized/http.rs
• src/rust/core/src/normalized/mod.rs
• src/rust/core/src/normalized/parameter.rs
• src/rust/core/src/normalized/request_body.rs
• src/rust/core/src/normalized/schema.rs
• src/rust/core/src/openapi/error.rs
• src/rust/core/src/openapi/format.rs
• src/rust/core/src/openapi/inspect/mod.rs
• src/rust/core/src/openapi/inspect/model.rs
• src/rust/core/src/openapi/loader.rs
• src/rust/core/src/openapi/mod.rs
• src/rust/core/src/openapi/normalize/mod.rs
• src/rust/core/src/openapi/raw.rs
• src/rust/core/src/openapi/source.rs
• src/rust/core/src/openapi/typed.rs
• src/rust/core/src/openapi/version.rs
• src/rust/core/src/operation_name.rs
• src/rust/core/src/privacy.rs
• src/rust/core/src/string_extensions.rs
• src/rust/core/src/support_information.rs

---

📝 Walkthrough

Walkthrough

This pull request adds comprehensive Rustdoc documentation across the httpgenerator-core library, introduces crate-level documentation with a missing_docs lint, and enhances the OpenAPI inspection module with statistics collection support. Nearly all changes are documentation additions with minimal structural modifications.

Changes

Comprehensive Rustdoc and library documentation enhancement

Layer / File(s)	Summary
Crate-level and core generator API documentation src/rust/core/src/lib.rs, src/rust/core/src/generator/mod.rs, src/rust/core/src/generator/modes.rs, src/rust/core/src/base_url.rs, src/rust/core/src/file_naming.rs, src/rust/core/src/model/mod.rs, src/rust/core/src/model/output_type.rs, src/rust/core/src/model/result.rs, src/rust/core/src/model/settings.rs	Crate-level documentation describing the httpgenerator-core library's purpose, #![warn(missing_docs)] lint for missing doc enforcement, module-level docs for the generator and model APIs, public re-exports for OutputType, GeneratorResult, HttpFile, and GeneratorSettings, and detailed field documentation for generator settings and output types.
Normalized OpenAPI model documentation src/rust/core/src/normalized/mod.rs, src/rust/core/src/normalized/document.rs, src/rust/core/src/normalized/http.rs, src/rust/core/src/normalized/parameter.rs, src/rust/core/src/normalized/request_body.rs, src/rust/core/src/normalized/schema.rs	Documentation for the renderer-friendly OpenAPI data model, including specification versions, servers, operations, HTTP methods, parameter locations, request bodies, and schemas, describing how normalized structures enable code generation without re-parsing.
OpenAPI loading, format detection, and inspection src/rust/core/src/openapi/mod.rs, src/rust/core/src/openapi/loader.rs, src/rust/core/src/openapi/raw.rs, src/rust/core/src/openapi/format.rs, src/rust/core/src/openapi/source.rs, src/rust/core/src/openapi/inspect/mod.rs, src/rust/core/src/openapi/inspect/model.rs	Documentation for raw document loading, format detection heuristics, source classification, and inspection workflows. OpenApiStats now derives Default and includes per-field docs; OpenApiInspection adds a stats: OpenApiStats field to collect operation counts and schema statistics.
OpenAPI version detection, error handling, and normalization src/rust/core/src/openapi/version.rs, src/rust/core/src/openapi/error.rs, src/rust/core/src/openapi/typed.rs, src/rust/core/src/openapi/normalize/mod.rs	Documentation for specification version detection, error enum variants (reformatted with multi-line field documentation), typed document parsing behavior, and document normalization entry points, clarifying fallback strategies and unsupported cases.
Utility function and support information documentation src/rust/core/src/operation_name.rs, src/rust/core/src/privacy.rs, src/rust/core/src/string_extensions.rs, src/rust/core/src/support_information.rs	Documentation for string transformation helpers (kebab-case, route casing, capitalization, spacing), operation name generation rules (operation_id preference, method/path fallback), authorization header redaction behavior, and deterministic anonymous identity/support key derivation with doctest examples.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

enhancement, rust

A documentation feast, so thorough and bright,
Rustdoc comments now shine with light,
Stats fields gather, inspection's more keen,
The cleanest API docs ever seen! 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main change: adding and improving rustdoc documentation for the httpgenerator-core crate.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch christianhelle/improve-rust-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

This PR improves the public docs.rs surface of httpgenerator-core by adding crate/module/item rustdoc throughout the Rust core library, and by enabling #![warn(missing_docs)] to keep documentation coverage from regressing over time.

Changes:

• Added crate-level/module-level rustdoc that explains the generation + normalization flow and how to use the OpenAPI helpers.
• Documented public types/APIs across model, normalized, openapi, and utility modules, including runnable (or no_run) examples.
• Enabled #![warn(missing_docs)] in httpgenerator-core to surface future public API documentation gaps as warnings.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/rust/core/src/support_information.rs	Documents support identity/key helpers and adds examples.
src/rust/core/src/string_extensions.rs	Documents string casing/format helpers and adds examples.
src/rust/core/src/privacy.rs	Documents authorization header redaction behavior and example.
src/rust/core/src/operation_name.rs	Documents operation name generation rules and examples.
src/rust/core/src/openapi/version.rs	Documents OpenAPI version enum + version detection helper.
src/rust/core/src/openapi/typed.rs	Documents typed OpenAPI parsing surface and limitations.
src/rust/core/src/openapi/source.rs	Documents source classification and OpenApiSource helpers.
src/rust/core/src/openapi/raw.rs	Documents raw document type + load/decode entry points.
src/rust/core/src/openapi/normalize/mod.rs	Documents top-level normalize entry points and examples.
src/rust/core/src/openapi/mod.rs	Adds module-level docs describing the OpenAPI API layers.
src/rust/core/src/openapi/loader.rs	Documents “loaded document” enum and load entry points.
src/rust/core/src/openapi/inspect/model.rs	Documents inspection result/stats structs and fields.
src/rust/core/src/openapi/inspect/mod.rs	Documents inspection entry points and example usage.
src/rust/core/src/openapi/format.rs	Documents format detection/sniffing and examples.
src/rust/core/src/openapi/error.rs	Documents OpenAPI-related error enums and their variants/fields.
src/rust/core/src/normalized/schema.rs	Documents normalized schema types used by renderer/samples.
src/rust/core/src/normalized/request_body.rs	Documents normalized request-body shapes and fields.
src/rust/core/src/normalized/parameter.rs	Documents normalized parameter shapes and fields.
src/rust/core/src/normalized/mod.rs	Adds module-level docs describing the normalized model.
src/rust/core/src/normalized/http.rs	Documents normalized HTTP method + parameter location enums.
src/rust/core/src/normalized/document.rs	Documents normalized document/server/operation structures.
src/rust/core/src/model/settings.rs	Documents generator settings and clarifies field meanings.
src/rust/core/src/model/result.rs	Documents HttpFile + GeneratorResult and adds examples.
src/rust/core/src/model/output_type.rs	Documents output grouping modes and their behavior.
src/rust/core/src/model/mod.rs	Adds module-level docs for settings/output types.
src/rust/core/src/lib.rs	Adds crate-level docs, re-export guidance, and enables warn(missing_docs).
src/rust/core/src/generator/modes.rs	Documents generate_http_files behavior and example.
src/rust/core/src/generator/mod.rs	Adds module-level docs for the renderer.
src/rust/core/src/file_naming.rs	Documents unique filename helper and example.
src/rust/core/src/base_url.rs	Documents base URL resolution rules and example.