none
Problems with XML documentation file

    Question

  • I have setup my (C#) project to generate the XML documentation from the comments on the classes.

    My comments look like this:

            /// <summary>
            /// Gets a collection of matching club records
            /// </summary>
            /// <param name="filter">Filter class</param>
            /// <param name="filter.name">Club Name (can be partial name)</param>
            /// <param name="filter.countryId">Country Id</param>
            /// <param name="filter.stateId">State Id</param>

    The XML document, however, is generated as:

                <summary>
                Gets a collection of matching club records
                </summary>
                <param name="filter">Filter class</param>
                <param name="filter.name.name">Club Name (can be partial name)</param>
                <param name="filter.countryId.countryId">Country Id</param>
                <param name="filter.stateId.stateId">State Id</param>

    With the property names on the filter duplicated.

    I have used this in another project (for auto documenting WebAPI with Swagger) and it works fine.
    Some computer, same version of Visual Studio, different project.

    I am at a loss to explain and correct.

    Any assistance would be most welcome.

    Thanks
    Peter

    Saturday, April 2, 2016 1:33 AM

Answers

  • For XML comments on code, you can only document the parameters on the method.  If you're passing an object and the parameter is named "filter", that's what the param element would document.  You can't document the members of the object with the param element.  See the XML Comments Guide for information on element usage.

    Parameter descriptions are typically kept fairly concise as they're shown in IntelliSense.  If you want to describe how the filter parameter should be used with the method, I'd suggest using the remarks element to provide more details.  If you generate a help file off of the XML comments, there will be a link to the filter parameter's type topic and, provided you've documented it with XML comments, details about its properties and their usage can be provided on it and its members as well which is probably more appropriate.

    Eric


    Saturday, April 2, 2016 7:21 PM

All replies

  • Hi Peter,

    Comment in XML is begin with "<!--" and end with "-->".

    like

    <!-- this is a comment -->

    it can be separate lines like

    <!--

    this is a comment

    and this is also comment

    -->

    Regards.

    Saturday, April 2, 2016 2:28 AM
  • For XML comments on code, you can only document the parameters on the method.  If you're passing an object and the parameter is named "filter", that's what the param element would document.  You can't document the members of the object with the param element.  See the XML Comments Guide for information on element usage.

    Parameter descriptions are typically kept fairly concise as they're shown in IntelliSense.  If you want to describe how the filter parameter should be used with the method, I'd suggest using the remarks element to provide more details.  If you generate a help file off of the XML comments, there will be a link to the filter parameter's type topic and, provided you've documented it with XML comments, details about its properties and their usage can be provided on it and its members as well which is probably more appropriate.

    Eric


    Saturday, April 2, 2016 7:21 PM