Skip to content

Summary documentation shall use '/// <summary>' instead of '// Summary:' #1347

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
RalfKoban opened this issue May 30, 2025 · 2 comments
Open

Comments

@RalfKoban
Copy link
Owner

The API documentation for summaries should use /// <summary> instead of // Summary: because /// <summary> creates XML comments that the .NET compiler understands. These comments show up in IntelliSense, help generate external documentation, and follow a structured format.

// Summary: will not be used by tools or IDEs to provide helpful info.

@RalfKoban
Copy link
Owner Author

Same applies for other comments such as // Returns or // Parameters: .

@RalfKoban
Copy link
Owner Author

So following comment should trigger a warning.

        // Summary:
        //     Gets the error message for the property with the given name.
        //
        // Parameters:
        //   columnName:
        //     The name of the property whose error message to get.
        //
        // Returns:
        //     The error message for the property. The default is an empty string ("").

It should be fixed into:

        /// <summary>
        /// Gets the error message for the property with the given name.
        /// </summary>
        /// <param name="columnName">
        /// The name of the property whose error message to get.
        /// </param>
        /// <returns>
        /// The error message for the property. The default is an empty string ("").
        /// </returns>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: To do
Development

No branches or pull requests

1 participant