Skip to content

Incorporate README.md into rustdoc where it wasn't already #2273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tarcieri merged 2 commits into from
Feb 3, 2026
+50 −30
Merged

Incorporate README.md into rustdoc where it wasn't already #2273

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c1584f4
Incorporate README.md into rustdoc where it wasn't already
tarcieri Feb 3, 2026
b91ba27
cipher/README.md: line length cleanup
tarcieri Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 0 additions & 1 deletion Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ cast_possible_wrap = "warn"
cast_precision_loss = "warn"
cast_sign_loss = "warn"
checked_conversions = "warn"
doc_markdown = "warn"
from_iter_instead_of_collect = "warn"
implicit_saturating_sub = "warn"
manual_assert = "warn"
Expand Down
7 changes: 4 additions & 3 deletions cipher/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@
[![Project Chat][chat-image]][chat-link]
[![Build Status][build-image]][build-link]

Traits which define the functionality of [block ciphers] and [stream ciphers].
Traits which define the functionality of [block ciphers], [block modes] and [stream ciphers].

See [RustCrypto/block-ciphers] and [RustCrypto/stream-ciphers] for algorithm
implementations which use these traits.
See [RustCrypto/block-ciphers] and [RustCrypto/stream-ciphers] for algorithm implementations which
use these traits.

## SemVer Policy

Expand Down Expand Up @@ -48,6 +48,7 @@ dual licensed as above, without any additional terms or conditions.
[//]: # (general links)

[block ciphers]: https://en.wikipedia.org/wiki/Block_cipher
[block modes]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
[stream ciphers]: https://en.wikipedia.org/wiki/Stream_cipher
[RustCrypto/block-ciphers]: https://github.com/RustCrypto/block-ciphers
[RustCrypto/stream-ciphers]: https://github.com/RustCrypto/stream-ciphers
8 changes: 1 addition & 7 deletions cipher/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,6 @@
//! This crate defines a set of traits which describe the functionality of
//! [block ciphers][1], [block modes][2], and [stream ciphers][3].
//!
//! [1]: https://en.wikipedia.org/wiki/Block_cipher
//! [2]: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation
//! [3]: https://en.wikipedia.org/wiki/Stream_cipher

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
Expand Down
4 changes: 1 addition & 3 deletions crypto-common/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
//! Common cryptographic traits.

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
)]
#![forbid(unsafe_code)]
#![warn(missing_docs, rust_2018_idioms, missing_debug_implementations)]

/// Hazardous materials.
pub mod hazmat;
Expand Down
3 changes: 3 additions & 0 deletions digest/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ blobby = { version = "0.4", optional = true }
const-oid = { version = "0.10", optional = true }
zeroize = { version = "1.7", optional = true, default-features = false }

[dev-dependencies]
sha2 = "0.11.0-rc.5"

[features]
default = ["block-api"]
block-api = ["block-buffer"] # Enable block API traits
Expand Down
10 changes: 7 additions & 3 deletions digest/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ hasher.update(data);
hasher.update("String data");
// Note that calling `finalize()` consumes hasher
let hash = hasher.finalize();
println!("Result: {:x}", hash);
println!("Result: {:?}", hash);
```

In this example `hash` has type [`Array<u8, U32>`][2], which is a generic
Expand All @@ -49,19 +49,23 @@ Alternatively you can use chained approach, which is equivalent to the previous
example:

```rust
use sha2::{Sha256, Digest};

let hash = Sha256::new()
.chain_update(b"Hello world!")
.chain_update("String data")
.finalize();

println!("Result: {:x}", hash);
println!("Result: {:?}", hash);
```

If the whole message is available you also can use convenience `digest` method:

```rust
use sha2::{Sha256, Digest};

let hash = Sha256::digest(b"my message");
println!("Result: {:x}", hash);
println!("Result: {:?}", hash);
```

### Generic code
Expand Down
24 changes: 12 additions & 12 deletions digest/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,16 @@
//! This crate provides traits which describe functionality of cryptographic hash
//! functions and Message Authentication algorithms.
#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![forbid(unsafe_code)]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
)]
#![warn(missing_docs, rust_2018_idioms, missing_debug_implementations)]

//! ## Structure
Copy link
Member

@newpavlov newpavlov Feb 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ideally it would be nice to move this section to the readme as well, though adding the hack for intra-crate links would be a bit annoying. Otherwise docs would look a bit strange since the license section will be before this one.

Copy link
Member Author

@tarcieri tarcieri Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's fine to have these sections which make heavy use of intra-rustdoc links immediately after the README.md.

It's very tedious to maintain those links otherwise.

//!
//! Traits in this repository are organized into the following levels:
//! Traits in this crate are organized into the following levels:
//!
//! - **High-level convenience traits**: [`Digest`], [`DynDigest`], [`Mac`].
//! Wrappers around lower-level traits for most common use-cases. Users should
Expand All @@ -24,15 +33,6 @@
//!
//! [`digest-io`]: https://docs.rs/digest-io

#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![forbid(unsafe_code)]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/6ee8e381/logo.svg"
)]
#![warn(missing_docs, rust_2018_idioms, missing_debug_implementations)]

#[cfg(feature = "alloc")]
#[macro_use]
extern crate alloc;
Expand Down
2 changes: 1 addition & 1 deletion signature/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
#![no_std]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc = include_str!("../README.md")]
#![doc(
html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
)]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![forbid(unsafe_code)]
#![allow(async_fn_in_trait)]
#![warn(
Expand Down