Macro component_location 

component_location!() { /* proc-macro */ }

Register a component location without attaching to a module.

This is a standalone macro that registers where a component’s code lives, without requiring an attribute on a module. It’s more flexible than #[in_component] and supports:

• Multiple components per file - Register several component locations
• File-level usage - No need to wrap code in a module
• Folder markers - Use in mod.rs to mark entire folders
• Role-based security - Control visibility in documentation

Syntax

component_location!(ComponentName);                    // Default: Internal (secure)
component_location!(ComponentName, role = public);     // Public: visible to everyone
component_location!(ComponentName, role = developer);  // Developer: devs + internal
component_location!(ComponentName, role = internal);   // Internal: team only (explicit)

Examples

Single component location:

// src/auth/jwt.rs
use waddling_errors_macros::component_location;

component_location!(Auth);  // Defaults to internal role

// ... your JWT code and diag! definitions ...

Multiple components in same file:

// src/shared/crypto.rs - shared between Auth and Crypto components
component_location!(Auth, role = internal);
component_location!(Crypto, role = developer);

// ... shared cryptographic utilities ...

Public documentation example:

// examples/auth_usage.rs
component_location!(Auth, role = public);

// ... example code for public documentation ...

Folder marker (in mod.rs):

// src/database/mod.rs
component_location!(Database);

pub mod connection;
pub mod queries;
pub mod migrations;

Generated Code

For component_location!(Auth, role = public) the macro generates:

pub mod __component_loc_auth {
    pub const COMPONENT: &str = "Auth";         // Preserves case to match component!
    pub const FILE: &str = "src/myfile.rs";     // file!() path
    pub const MODULE_PATH: &str = "mymod";      // module_path!()
    pub const ROLE: Option<Role> = Some(Role::Public);
     
    #[cfg(feature = "metadata")]
    pub fn register(registry: &mut DocRegistry) {
        registry.register_component_location_with_role(COMPONENT, FILE, ROLE);
    }
}

Accessing Generated Constants

Access constants via the generated marker module __component_loc_<name>:

component_location!(Auth, role = public);
component_location!(Crypto, role = developer);

fn main() {
    // Access constants (preserves original case to match component! registration)
    assert_eq!(__component_loc_auth::COMPONENT, "Auth");
    assert_eq!(__component_loc_crypto::COMPONENT, "Crypto");
     
    // Check file paths
    println!("Auth location: {}", __component_loc_auth::FILE);
}

Registration

With auto-register feature, locations are registered automatically via ctor. Manual registration is also supported:

let mut registry = DocRegistry::new("myapp", "1.0.0");
__component_loc_auth::register(&mut registry);
__component_loc_crypto::register(&mut registry);

Why Use This Over #[in_component]?

Feature	#[in_component]	component_location!
Attach to module	✅ Required	❌ Not needed
Multiple per file	❌ Awkward	✅ Easy
File-level use	❌ Needs wrapper	✅ Direct
Non-module items	⚠️ Creates sibling mod	✅ Clean

Use component_location! when you want to mark locations without restructuring your code around modules.