Crate 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.

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.

1. Root module

   Select root by first argument of doc_share and doc_file.

2. Fragment key

   Select fragment key after file path (doc_file only).

   See “Fragment key” section in doc_file for more details.

3. 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

4. Section module

   Select sub section recursively in target Rust item.

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

5. 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.

• Normal path error
• Self path warning

Re-exports

pub use rustdoc_copy_macro;

Modules

docs

Modules for documentation.

prelude

Crate’s prelude.

Macros

doc_file

Include Markdown file as given name module.

Attribute Macros

doc_on_only

Disables documentations if doc_on feature flag is OFF.

doc_share

Shares documentation comment as given name module.