doxed/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! [![crates.io](https://img.shields.io/crates/v/doxed.svg)](https://crates.io/crates/doxed)
4//! ![license](https://img.shields.io/badge/license-Apache%202.0-blue)
5//! ![tests](https://github.com/npmccallum/doxed/actions/workflows/test.yml/badge.svg)
6//! ![lints](https://github.com/npmccallum/doxed/actions/workflows/lint.yml/badge.svg)
7//!
8//! **Doxed** is a crate for making Rust doc strings available at runtime.
9//!
10//! This crate provides a trait, `Doxed`, which can be derived for any type to
11//! make its doc strings available at runtime. The doc string is specified
12//! using the `#[doc = "..."]` attribute or, more commonly, the Rust doc
13//! comment (`///`).
14//!
15//! Note that when deriving `Doxed`, the doc string is not modified in any way.
16//! This preserves the original formatting, including leading whitespace and
17//! line breaks. If you want to do any processing on the doc string, you can
18//! easily do so at runtime without additional derive magic.
19//!
20//! # Example
21//!
22//! ```rust
23//! use doxed::Doxed;
24//!
25//! /// This is an example struct.
26//! ///
27//! /// Multiple lines are supported.
28//! #[doc = "So are manual doc attributes."]
29//! #[derive(Doxed)]
30//! struct Example<'a, T>(&'a T);
31//!
32//! assert_eq!(Example::<()>::DOX, &[
33//!     " This is an example struct.",
34//!     "",
35//!     " Multiple lines are supported.",
36//!     "So are manual doc attributes."
37//! ]);
38//! ```
39
40#![no_std]
41
42#[cfg(feature = "derive")]
43pub use doxed_derive::Doxed;
44
45/// A trait for types that have a doc string.
46pub trait Doxed {
47    /// The doc string(s) for the type.
48    const DOX: &'static [&'static str];
49}