no-incode-comments

A Rust procedural macro that allows you to keep documentation for your code in external Markdown files instead of inline doc comments.

Purpose

This library solves the problem of maintaining documentation alongside your code by:

1. Letting you write documentation in proper Markdown files
2. Linking those files to your code through a simple attribute macro
3. Automatically importing the documentation at compile time

This approach has several benefits:

• Better organization of documentation
• Support for rich Markdown features
• Easier maintenance of extensive documentation
• Improved separation of concerns

Installation

Add this to your Cargo.toml:

[dependencies]
no-incode-comments = "0.1.0"

Usage

1. Create a Markdown file for your documentation (e.g., docs/my_function.md):

# MyFunction

This is documentation for my_function.
It will be rendered as the doc comment for the function.

# AnotherSection
This section won't be included since we're only importing the "MyFunction" section.

2. Use the external_doc macro to import the documentation:

use no_incode_comments::external_doc;

#[external_doc(path = "docs/my_function.md", key = "MyFunction")]
pub fn my_function() {
    // Function implementation
}

The path parameter specifies the Markdown file location, and the key parameter indicates which section (by heading) to import.

How It Works

The procedural macro:

1. Reads the specified Markdown file
2. Parses it to extract the section with the matching header (key)
3. Converts that section into Rust doc comments (///)
4. Applies those comments to your function

Example

See the sample code in main.rs and the corresponding documentation in docs/sample_file.md.

License

This project is available under the MIT License.