XML documentation in C #

    Greetings, Habr-donors!
    Today we will talk about one interesting and useful feature of the C # language, which will help us in documenting the code. It is called XML Documentation or XML Documentation Comments. These are special XML tags that are contained in the comments and describe the properties or methods in a particular file. So, there are at least three good reasons why you should always populate XML comments.

    Firstly, this approach allows you to standardize comments in your project and, in principle, in all C # projects, and the standards in our business are almost always good. Secondly, IntelliSense will automatically display information about documented methods and parameters, as well as for methods built into the framework. This will greatly facilitate the work and save time for you and other developers working with you. And thirdly, at the compilation stage, you can generate an XML file that will contain all the comments in a convenient format, and you can already do anything with this file.

    Now we’ll review the recommended tags for use. In order to start entering them, you must first put "///".

    TagIs used for
    one line of source code
    many lines of source code
    usage example, can be used with tag
    allows you to specify which exceptions our method can throw
    allows you to put a link to a file that contains comments using XPath
    regular list
    and this is a regular paragraph
    method parameter descriptions, each parameter is described separately
    allows you to specify that the word inside the tag is a parameter
    allows you to describe the access rights to the method
    additional information besides tag
    a description of what the method returns
    allows you to specify links
    text in the section “See also”
    general description
    allows you to describe properties

    /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.

    /// Сколько раз передать привет
    /// Сама строка с приветами
    public string HelloHabr(int repeat)
         string result = "";
         for (int i = 0; i < repeat; i++)
             result += "Hello, HabraHabr!\n";
         return result;

    And here is how our method will be shown in IntelliSense:

    isense1.jpg - image uploaded to Picamatic
    isense2.jpg - Picamatic - upload your images
    Details about everything can be read as always on MSDN .

    Well, for starters, probably all. Begin by documenting your code correctly, and I will prepare a couple more articles on this topic, if this turns out to be relevant.

    Also popular now: