XML Comments don't handle parameters in complex models nicely

[ghost]

When doing XML comment documentation, it's considered desirable (and there are compiler warnings for it) to have the XML param tags match up to the actual parameters of the method. This unfortunately doesn't work well in Swashbuckle, since a complex model may be used to add more query parameters to the api:

class Model {
    int Param1;
    int Param2;
};

[HttpGet]
HttpResultMessage Action([FromUri(Name = "")] Model params) {
    /* ... */
}

In this case, the XML documentation "should" document the param params, but the documentation should be for Param1 and Param2 in the API. You can document the params:

/// <param name="Param1">This is parameter 1.</param>
/// <param name="Param2">This is parameter 2.</param>

but this violates convention and triggers compiler warnings.

My suggestion is to allow another tag to be used for parameters, like:

/// <swashParam name="Param1">This is parameter 1.</param>
/// <swashParam name="Param2">This is parameter 2.</param>

which would allow thise to be documented in a way that clearly separates them from the C# parameters.

[Chris3773]

Another option would be to pull from the summary documentation from the model.

class Model {
    /// <summary>
    /// This is parameter 1.
    /// </summary>
    int Param1;

    /// <summary>
    /// This is parameter 2.
    /// </summary>
    int Param2;
};