1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
//! Procedual macros for crate `rustdoc_copy`.
//!
//! _The author of this crate is not good at English._
//! _Forgive me if the document is hard to read._
use proc_macro as pm;
/// Includes Markdown file as given name module.
/// Shares documentation comment as given name module.
///
/// # `doc_share::Self`
///
/// `doc_share` enables `doc_share::Self` in API paths in document.
/// This is similar to `Self` at there. But while the latter changes
/// the meaning of the target before and after copying the document,
/// the former keeps the target.
///
/// In shortcut style link, `"doc_share::"` prefix is removed
/// at link text. For example, ``[`doc_share::Self::item`]`` is
/// parsed as ``[`Self::item`](SomeTarget::item)``.
///
/// # Examples
///
/// ```
/// use rustdoc_copy::prelude::*;
///
/// /// My function.
/// #[doc_share(doc)]
/// pub fn my_func() {
/// println("`my_func` is called.");
/// }
///
/// #[doc = doc::all!()]
/// pub fn my_func_alias() {
/// my_func();
/// }
/// ```
/// Disables documentations if `doc_on` feature flag is OFF.
///
/// # Build acceleration
///
/// This crate is bit heavy (As of 2026, default build takes several seconds
/// on the author's environment). Because it includes parser crates for Rust
/// and Markdown text. And sadly, `Cargo.toml` has `dev-dependencies` but no
/// `doc-dependencies`. As a result, outside of documentation, this crate is
/// nothing more than a heavy burden.
///
/// For this solution, `doc_on` feature flag and [`doc_on_only`](Self)
/// attribute are used in combination. First, if `doc_on` is OFF, most items
/// are replaced with items that have only their entry points. This speed up
/// the build process. However, since document copy is not generated, its
/// importing part cause compilation errors. Here, to avoid this error,
/// [`doc_on_only`](Self) generates empty document when `doc_on` is OFF.
///
/// # Build settings
///
/// This attribute is often used with settings like followings.
///
/// - `Cargo.toml`
///
/// ```text
/// [package]
/// name = "example"
/// version = "0.1.0"
/// edition = "2024"
///
/// [dependencies]
/// rustdoc_copy = { version = "0.2.0", default-features = false }
///
/// [features]
/// doc_on = ["rustdoc_copy/doc_on"]
///
/// [package.metadata.docs.rs]
/// all-features = true
/// ```
///
/// - `.vscode/settings.json`
///
/// ```text
/// {"rust-analyzer.cargo.allFeatures": true}
/// ```
///
/// This example roughly does the following.
///
/// - Define a feature flag named `doc_on` in the crate.
/// - Propagates it to the feature flag of the same name in this crate.
/// - Configures to enable the `doc_on` flag in [`docs.rs`](https://docs.rs/).
/// - Configures to enable the `doc_on` flag in IDE (VS Code).
///
/// In this case, following command generate rustdoc locally.
///
/// ```text
/// cargo doc --features doc_on
/// ```
///
/// # Examples
///
/// ```
/// use rustdoc_copy::prelude::*;
///
/// /// My function.
/// #[doc_share(doc)]
/// pub fn my_func() {
/// println("`my_func` is called.");
/// }
///
/// #[doc_on_only]
/// #[doc = doc::all!()]
/// pub fn my_func_alias() {
/// my_func();
/// }
/// ```