Get summary and description from doc comments

[kmdreko]

I've just created a library, aidecomment, that allows you to provide the operation summary and description of an axum handler based on doc comments. Example:

/// Adds a new pet
///
/// This puts a new pet in the store inventory. This will be immediately
/// available for customers unless its visibility is set to "private". This
/// will fail if the `id` is provided and conflicts with another pet.
#[aidecomment]
async fn post_pet(create_pet_payload: Json<CreatePetPayload>) -> &'static str {
    "new pet created"
}

The first line will be set as the summary and the rest will be set as the description.

I thought it was a natural way to document an endpoint's behavior and glad that a simple macro can provide it to aide. I don't intend this to replace anything - only offer an alternative - I appreciate aide's code-first design in most other respects. I only whipped this up in a single evening so there may be some bugs or missing edge cases, but I offer it for others and am looking for input in any case.

[tamasfe]

Adding invisible parameters for customizing docs seems pretty clever, interesting stuff!

I am not a fan of using doc comments for documenting the API as this takes away the ability to document the handler itself, or worse the two can mix and you can leak implementation-related details into the public API documentation. I see the appeal though and having the ability of doing this seamlessly is definitely great.