While working with swagger documentation in an API, we have to enable the XML file to be generated for documentation from the project setting. For this reason, all the public members in the project solution start giving the warning "CS1591: Missing XML comment for publicly visible type or member"
we can simply define the XML comment for those members, and the same warning will disappear. But what about those members who are not a part of the swagger documentation? If we ignore them, then there will be lots of warnings in the code, which looks very ugly in the code.
In this article we will discuss how to resolve the "CS1591 missing XML comment for publicly visible type or member" warning by using one of three different solutions.
- Create an XML Comment for All Public Members
- Disable Warning by Decorating Each Public Member
- Disable all warnings at the project level. (Recommended)
Define XML Comment for All Public Members
The best way is to define the XML comment for all public members, whether it is part of the swagger UI document or not. Because of comments, our method becomes more meaningful, which helps new developers learn about the method by comments instead of going through the code and understanding the logic.
Suppress Warning by Decorating each Public Member
Even though the first approach has lots of advantages but it requires lots of time and it will increase the size of the project .
The alternate solution to the preceding mentioned problem is we can suppress each public member by decorating with the following line, which does not require you to provide the XML comment.
#pragma warning disable CS1591
If you don't know the syntax, then simply follow the visual studio suggestion by keeping the mouse on a specific method or member.
Suppress all Warnings at Project Level
The previous two approaches necessitate a significant amount of time spent either defining the XML comment or disabling the warning for each project member.
To save time and minimise the swagger comment related warnings, we can disable these warnings at the project level itself with just one line of configuration. To achieve this, follow the following steps:
Right-click on the api project solution & find the properties
or just use Alt + Enter by putting control of project solution which opens the following window, find the options by following the below image & enter the 1591 in the suppress warnings text box & save it.
 |
Now check any class file. You will not see any warnings related to the swagger XML comment.
Summary
I hope this article helped you to fix Warning CS1591: Missing XML comment for publicly visible type or member.
Post a Comment