Description fields overshadow Summary fields

[pillowfication]

Some nodes in OpenAPI (e.g. the Path Item Object) can have both a summary field and a description field. Kiota will always use the description field if it exists, otherwise falling back to the summary field as the node's only description. While there seems to be a lot of variance in how these two fields are utilized, it would be nice if they were both retained somehow.

https://github.com/microsoft/kiota/blob/9f3c55fca68a0ec94abab7edcde0cc45463a9c67/src/Kiota.Builder/Extensions/OpenApiUrlTreeNodeExtensions.cs#L142

Current Behavior

A common paradigm is to use summary for short descriptions, and additionally add a description as a more detailed summary OR to supplement the summary with auxiliary details.

"paths": {
  "/foo": { "get": {
    "summary": "Get a Foo",
    "description": "Returns a high-quality, made-to-order Foo"
  } },
  "/bar": { "get": {
    "summary": "Get a Bar",
    "description": "Make sure you get a Foo first"
  } }
}

In this example, the generated docs for GET /bar become awkward.

/// <summary>
/// Make sure you get a Foo first
/// </summary>
public async Task<BarView?> GetAsync() { }

Expected Behavior

Ideally I would like both the summary and description to be preserved somehow, when they are both present. C# has both the <summary/> and <remarks/> tags that can house the two fields.

/// <summary>
/// Get a Bar
/// <summary>
/// <remarks>
/// Make sure you get a Foo first
/// </remarks>
public async Task<BarView?> GetAsync() { }

For languages like Java, the two fields can be concatenated.

/**
 * Get a Bar
 * <p>
 * Make sure you get a Foo first
 * @return a CompletableFuture of BarView
 */
@javax.annotation.Nonnull
public java.util.concurrent.CompletableFuture<BarView> get() { }

When only one of summary or description is used, the current behavior is fine.

[baywet]

Thanks for your interest in kiota and for your suggestion. Yes we could improve the doc comments and the descriptions by including both the summary and the description when they are available. We should probably add a summary field in the description class, switch existing code to this, and then add the description to the description field if it's present as you suggest. Is this something you'd be willing to submit a pull request for?