rustdoc_copy

Rustdoc comment copy helper.

The author of this crate is not good at English.
Forgive me if the document is hard to read.

Core items

doc_share - Copy rustdoc comment from other rustdoc comment.
doc_file - Copy rustdoc comment from Markdown file.
doc_on_only - Stop documentation for build speed.

Highlights

😊 Pros

Document path supports partial copy in various methods.
Link adjustments prevents broken links in various situations.
doc_file supports heading level adjusting.

🤔 Cons

No tooltip display at IDE (expecting future IDE).
No file update detecting at IDE (expecting futrue Rust).
No root document sharing (expecting futrue Rust).
Miss copy of document (expecting futrue crates for Markdown).
Mysterious compilation troubles (maybe not a big deal).

Examples

Simple copy

use rustdoc_copy::prelude::*;

/// This is my function.
#[doc_share(doc)]
pub fn my_func() {
    println!("`my_func` is called.");
}

#[doc = doc::all!()]
pub fn my_func_alias() {
    my_func();
}

Partial copy

use rustdoc_copy::prelude::*;

/// This is my function.
/// 
/// # Some Notes
/// 
/// Message print only.
#[doc_share(doc)]
pub fn my_func() {
    println!("`my_func` is called.");
}

/// This is my function alias.
#[doc = doc::sub::some_notes::all!()]
pub fn my_func_alias() {
    my_func();
}

With members

use rustdoc_copy::prelude::*;

/// This is my struct.
#[doc_share(doc)]
pub struct MyStruct {
    /// Field 1.
    pub field1: i32,
    /// Field 2.
    pub field2: i32,
}

#[doc_share(doc_impl)]
impl MyStruct {
    /// Method 1.
    fn method1(&self) {}
    /// Method 2.
    fn method2(&self) {}
}

#[doc = doc::base::all!()]
pub struct MyStructAlias {
    #[doc = doc::side::field1::all!()]
    pub field1: i32,
    #[doc = doc::side::field2::all!()]
    pub field2: i32,
}

impl MyStructAlias {
    #[doc = doc_impl::side::method1::all!()]
    fn method1(&self) {}
    #[doc = doc_impl::side::method2::all!()]
    fn method2(&self) {}
}

File copy

- src/lib.rs

//! Welcome to my crate API document.
#![doc = doc::sub::examples::all!()]

doc_file!(doc, "README.md#");

use rustdoc_copy::prelude::*;

pub fn some_func() -> i32 {
    42
}

- README.md

# my_crate

This crate is ...

## Examples

```rust
use my_crate::some_func;

assert_eq!(some_func(), 42);
```

Tips

Document path

Partial document is specified by path with following components.

Root module

Select root by first argument of doc_share and doc_file.
Fragment key

Select fragment key after file path (doc_file only).

See "Fragment key" section in doc_file for more details.
Item module

Select Rust item in target root or fragment.

ID Description

No selection For no member item

base Base item

side::member Member item
Section module

Select sub section recursively in target Rust item.

ID Description

No selection Root section

sub::section Named section

ID	Description
No selection	For no member item
base	Base item
side::member	Member item

ID	Description
No selection	Root section
sub::section	Named section

Parts macro

Select block parts in target section.

ID	Description
`head!`	First block (Mrakdown heading fit this group)
`body!`	Subsequent blocks
`defs!`	Definitions (Root only)
`subs!`	All sub sections
`top!`	`head!` + `body!`
`all!`	`top!` + `subs!` + `defs!`

Title ID

Section identification by title has two subtly different styles.

Common rule
- All uppercase characters are converted to lowercase.
- Special characters like punctuation and Emoji are ignored.
Global style
- This style is used in fragment key in doc_file.
- This style follows heading anchor rule of GFM.
- Spaces in the titles are replaced into hyphen ('-').
- Sequential numers are used if same titles exist in the one document.
Local style
- This style is used in section ID in document path.
- This style follows naming rule of Rust module.
- Spaces in the titles are replaced into underscore ('_').
- Sequential numbers are used if same title exists in sibling sections.
- Long ID or path can shorten with use and as keywords.

Link adjustments

To prevent broken links, folowing mechanisms are supported.

Link embeding

Up for partial copy, reference style link is converted to inline style.

(In contrast, footnotes are not adjusted. Because they lack embeding ability. So, use defs! macro instead.)
Special Self

Up for Self keyword meaning changes, doc_share::Self is prepared.

See "doc_share::Self" section in doc_share document for more detail.

(In contrast, self and super keywords do not have a mechanism for doc_share. Because attribute macros can not know module of item. So, use target name directly instead.)
Copy guard

Up for API links in README.md, URLs under the copy guard path are ignored.

See "Link copy guard" section in doc_file document for more detail.

Trouble shooting

No tooltip display at IDE

This crate uses the doc attribute frequently for document importing. But documentation by doc attributes are reflected only rustdoc file, not IDE tooltips (At least VS Code with rust-analyzer in 2026).

No file update detecting at IDE

At doc_file, argument file is not tracked on real time from IDE. Therefore, error detection and autocompletion at IDE is based on old Markdown headings. This state will remain until rebuild. (I wonder this issue will be resolved by proc_macro::tracked::path in the future.)

No root document shareing

At doc_share, root documents of Rust files are not supported. This is because notation like #![doc_share(doc)] are not supported. (I wonder this issue will be resolved by inner macro attribute in the future.)

Miss copy of document

The content of documents may change slightly when copied. This is the impact of the crate for CommonMark that this crate depends on. The crate is high precision, but currently, not perfect. Therefore, when using elaborate notation, please inspect the outputs by yourself.

Mysterious compilation troubles

Following compilation troubles maybe a bit tough.

History

See CHANGELOG.

rustdoc_copy 0.2.0