diff --git a/docs/csharp/codedoc.md b/docs/csharp/codedoc.md index 2a9c67e7b2805..67fd287b128f7 100644 --- a/docs/csharp/codedoc.md +++ b/docs/csharp/codedoc.md @@ -2,9 +2,9 @@ title: Documenting your code description: Documenting your code keywords: .NET, .NET Core -author: dotnet-bot +author: tsolarin manager: wpickett -ms.date: 06/20/2016 +ms.date: 08/24/2016 ms.topic: article ms.prod: .net-core ms.technology: .net-core-technologies @@ -12,16 +12,1255 @@ ms.devlang: dotnet ms.assetid: 8e75e317-4a55-45f2-a866-e76124171838 --- -# 🔧 Documenting your code - -> **Note** -> -> This topic hasn’t been written yet! -> -> We welcome your input to help shape the scope and approach. You can track the status and provide input on this -> [issue](https://github.com/dotnet/core-docs/issues/494) at GitHub. -> -> If you would like to review early drafts and outlines of this topic, please leave a note with your contact information in the issue. -> -> Learn more about how you can contribute on [GitHub](https://github.com/dotnet/core-docs/blob/master/CONTRIBUTING.md). -> +# Documenting your code + +XML documentation comments are a special kind of comment, added above the definition of any user defined type or member. +They are special because they can be processed by the compiler to generate an XML documentation file at compile time. +The compiler generated XML file can be distributed alongside your .NET assembly so that Visual Studio and other IDEs can show quick information about types or members when performing intellisense. +Additionally the XML file can be run through tools like [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to generate full on API reference websites. + +XML documentation comments like all other comments are ignored by the compiler, to enable generation of the XML file add `"xmlDoc":true` under `buildOptions` in your `project.json` when using .NET Core or use the `/doc` compiler option for the .NET framework. +Go [here](https://msdn.microsoft.com/en-us/library/3260k4x7.aspx) to learn how to enable XML documentation generation in Visual Studio. + +XML documentation comments are characterized by triple forward slashes (`///`) and an XML formatted comment body. + +```csharp +/// +/// This class does something. +/// +public class SomeClass +{ + +} +``` + +## Walkthrough + +Let's walk through documenting a very basic math library to make it easy for new developers to understand/contribute and for third party developers to use. + +Here's code for the simple math library: + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +public class Math +{ + // Adds two integers and returns the result + public static int Add(int a, int b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Adds two doubles and returns the result + public static double Add(double a, double b) + { + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Subtracts an integer from another and returns the result + public static int Subtract(int a, int b) + { + return a - b; + } + + // Subtracts a double from another and returns the result + public static double Subtract(double a, double b) + { + return a - b; + } + + // Multiplies two intergers and returns the result + public static int Multiply(int a, int b) + { + return a * b; + } + + // Multiplies two doubles and returns the result + public static double Multiply(double a, double b) + { + return a * b; + } + + // Divides an integer by another and returns the result + public static int Divide(int a, int b) + { + return a / b; + } + + // Divides a double by another and returns the result + public static double Divide(double a, double b) + { + return a / b; + } +} +``` + +The sample library supports four major arithmetic operations `add`, `subtract`, `multiply` and `divide` on `int` and `double` datatypes. + +Now you want to be able to create an API reference document from your code for third party developers who use your library but don't have access to the source code. +As mentioned earlier XML documentation tags can be used to achieve this, You will now be introduced to the standard XML tags the C# compiler supports. + +### <summary> + +First off is the `` tag and as the name suggests you use it to add brief information about a type or member. +I'll demonstrate its use by adding it to the `Math` class definition and the first `Add` method, feel free to apply it to the rest of your code. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + // Adds two integers and returns the result + /// + /// Adds two integers and returns the result. + /// + public static int Add(int a, int b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } +} +``` + +The `` tag is super important and you are strongly advised to include it because its content is the primary source of type or member description in intellisense and the resulting API reference document. + +### <remarks> + +You use the `` tag to add information about types or members, supplementing the information specified with ``. +In this example you'll just add it to the class. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +/// +/// This class can add, subtract, multiply and divide. +/// +public class Math +{ + +} +``` + +### <returns> + +As the name suggests you use the `` tag in the comment for a method declaration to describe its return value. +Like before this will be illustrated on the first `Add` method go ahead an implement it on other methods. + +```csharp +// Adds two integers and returns the result +/// +/// Adds two integers and returns the result. +/// +/// +/// The sum of two integers. +/// +public static int Add(int a, int b) +{ + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; +} +``` + +### <value> + +The `` works similarly to the `` tag except that you use it for properties. +Assuming your `Math` library had a static property called `PI` here's how you'll use this tag: + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +/// +/// This class can add, subtract, multiply and divide. +/// These operations can be performed on both integers and doubles +/// +public class Math +{ + /// Gets the value of PI. + public static double PI { get; } +} +``` + +### <example> + +You use the `` tag to include an example in your XML documentation. +This involves using the child `` tag. + +```csharp +// Adds two integers and returns the result +/// +/// Adds two integers and returns the result. +/// +/// +/// The sum of two integers. +/// +/// +/// +/// int c = Math.Add(4, 5); +/// if (c > 10) +/// { +/// Console.WriteLine(c); +/// } +/// +/// +public static int Add(int a, int b) +{ + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; +} +``` + +The `code` tag preserves line breaks and indentation for longer examples. + +### <para> + +You may find you need to format the content of certain tags and that's where the `` tag comes in. +You usually use it inside a tag, such as ``, or ``, and lets you divide text into paragraphs. +You can go ahead and format the contents of the `` tag for your class definition. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +/// +/// This class can add, subtract, multiply and divide. +/// These operations can be performed on both integers and doubles. +/// +public class Math +{ + +} +``` + +### <c> + +Still on the topic of formatting, you use the `` tag for marking part of text as code. +It's like the `` tag but inline and is great when you want to show a quick code example as part of a tag's content. +Let's update the documentation for the `Math` class. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + +} +``` + +### <exception> + +There's no getting rid of exceptions, there will always be exceptional situations your code is not built to handle. +Good news is there's a way to let your developers know that certain methods can throw certain exceptions and that's by using the `` tag. +Looking at your little Math library you can see that both `Add` methods throw an exception if a certain condition is met, not so obvious though +is that both `Divide` methods will throw as well if the parameter `b` is zero. Now go ahead to add exception documentation to these methods. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + /// + /// Adds two integers and returns the result. + /// + /// + /// The sum of two integers. + /// + /// + /// + /// int c = Math.Add(4, 5); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// Thrown when one parameter is max + /// and the other is greater than 0. + public static int Add(int a, int b) + { + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + /// + /// Adds two doubles and returns the result. + /// + /// + /// The sum of two doubles. + /// + /// Thrown when one parameter is max + /// and the other is greater than zero. + public static double Add(double a, double b) + { + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + /// + /// Divides an integer by another and returns the result. + /// + /// + /// The division of two integers. + /// + /// Thrown when a division by zero occurs. + public static int Divide(int a, int b) + { + return a / b; + } + + /// + /// Divides a double by another and returns the result. + /// + /// + /// The division of two doubles. + /// + /// Thrown when a division by zero occurs. + public static double Divide(double a, double b) + { + return a / b; + } +} +``` + +The `cref` attribute represents a reference to an exception that is available from the current compilation environment. +This can be any type defined in the project or a referenced assembly, the compiler will issue a warning if its value cannot be resolved. + +### <see> + +While documenting your code with XML tags you might reach a point where you need to add some sort of reference to another part of the code to make your reader understand it better. +The `` tag is one that let's you create clickable links to documentation pages for other code elements. In our next example we'll create a clickable link between the two `Add` methods. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + /// + /// Adds two integers and returns the result. + /// + /// + /// The sum of two integers. + /// + /// + /// + /// int c = Math.Add(4, 5); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// Thrown when one parameter is max + /// and the other is greater than 0. + /// See to add doubles. + public static int Add(int a, int b) + { + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + /// + /// Adds two doubles and returns the result. + /// + /// + /// The sum of two doubles. + /// + /// Thrown when one parameter is max + /// and the other is greater than zero. + /// See to add integers. + public static double Add(double a, double b) + { + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } +} +``` + +The `cref` is a **required** attribute that represents a reference to a type or its member that is available from the current compilation environment. +This can be any type defined in the project or a referenced assembly. + +## <seealso> + +You use the `` tag in the same way you do the `` tag, the only difference is that it's content is typically broken into a "See Also" section not that different from +the one you sometimes see on the MSDN documentation pages. Here we'll add a `seealso` tag on the integer `Add` method to reference other methods in the class that accept interger parameters: + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + /// + /// Adds two integers and returns the result. + /// + /// + /// The sum of two integers. + /// + /// + /// + /// int c = Math.Add(4, 5); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// Thrown when one parameter is max + /// and the other is greater than 0. + /// See to add doubles. + /// + /// + /// + public static int Add(int a, int b) + { + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } +} +``` + +The `cref` attribute represents a reference to a type or its member that is available from the current compilation environment. +This can be any type defined in the project or a referenced assembly. + +### <param> + +You use the `` tag for describing the parameters a method takes. Here's an example on the double `Add` method: +The parameter the tag describes is specified in the **required** `name` attribute. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + /// + /// Adds two doubles and returns the result. + /// + /// + /// The sum of two doubles. + /// + /// Thrown when one parameter is max + /// and the other is greater than zero. + /// See to add integers. + /// A double precision number. + /// A double precision number. + public static double Add(double a, double b) + { + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } +} +``` + +### <typeparam> + +You use `` tag just like the `` tag but for generic type or method declarations to describe a generic parameter. +Go ahead and add a quick generic method to your `Math` class to check if one quantity is greater than another. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + /// + /// Checks if an IComparable is greater than another. + /// + /// A type that inherits from the IComparable interface. + public static bool GreaterThan(T a, T b) where T : IComparable + { + return a.CompareTo(b) > 0; + } +} +``` + +### <paramref> + +Sometimes you might be in the middle of describing what a method does in what could be a `` tag and you might want to make a reference +to a parameter, the `` tag is great for just this. Let's update the summary of our double based `Add` method. Like the `` tag +the parameter name is specified in the **required** `name` attribute. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + /// + /// Adds two doubles and and returns the result. + /// + /// + /// The sum of two doubles. + /// + /// Thrown when one parameter is max + /// and the other is greater than zero. + /// See to add integers. + /// A double precision number. + /// A double precision number. + public static double Add(double a, double b) + { + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } +} +``` + +### <typeparamref> + +You use `` tag just like the `` tag but for generic type or method declarations to describe a generic parameter. +You can use the same generic method you previously created. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +public class Math +{ + /// + /// Checks if an IComparable is greater than another. + /// + /// A type that inherits from the IComparable interface. + public static bool GreaterThan(T a, T b) where T : IComparable + { + return a.CompareTo(b) > 0; + } +} +``` + +### <list> + +You use the `` tag to format documentation information as an ordered list, unordered list or table. +You'll make an unordered list of every math operation your `Math` library supports. + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +/// +/// Add +/// Addition Operation +/// +/// +/// Subtract +/// Subtraction Operation +/// +/// +/// Multiply +/// Multiplication Operation +/// +/// +/// Divide +/// Division Operation +/// +/// +/// +public class Math +{ + +} +``` + +You can make an ordered list or table by changing the `type` attribute to `number` or `table` respectively. + +### Putting it all together + +You've followed this tutorial and applied the tags to your code where necessary, your code should now look similar to the following: + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +/// The main Math class. +/// Contains all methods for performing basic math functions. +/// +/// +/// Add +/// Addition Operation +/// +/// +/// Subtract +/// Subtraction Operation +/// +/// +/// Multiply +/// Multiplication Operation +/// +/// +/// Divide +/// Division Operation +/// +/// +/// +/// +/// This class can add, subtract, multiply and divide. +/// These operations can be performed on both integers and doubles. +/// +public class Math +{ + // Adds two integers and returns the result + /// + /// Adds two integers and and returns the result. + /// + /// + /// The sum of two integers. + /// + /// + /// + /// int c = Math.Add(4, 5); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// Thrown when one parameter is max + /// and the other is greater than 0. + /// See to add doubles. + /// + /// + /// + /// An integer. + /// An integer. + public static int Add(int a, int b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Adds two doubles and returns the result + /// + /// Adds two doubles and and returns the result. + /// + /// + /// The sum of two doubles. + /// + /// + /// + /// double c = Math.Add(4.5, 5.4); + /// if (c > 10) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// Thrown when one parameter is max + /// and the other is greater than 0. + /// See to add integers. + /// + /// + /// + /// A double precision number. + /// A double precision number. + public static double Add(double a, double b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Subtracts an integer from another and returns the result + /// + /// Subtracts from and returns the result. + /// + /// + /// The difference between two integers. + /// + /// + /// + /// int c = Math.Subtract(4, 5); + /// if (c > 1) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to subtract doubles. + /// + /// + /// + /// An integer. + /// An integer. + public static int Subtract(int a, int b) + { + return a - b; + } + + // Subtracts a double from another and returns the result + /// + /// Subtracts a double from another double and returns the result. + /// + /// + /// The difference between two doubles. + /// + /// + /// + /// double c = Math.Subtract(4.5, 5.4); + /// if (c > 1) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to subtract integers. + /// + /// + /// + /// A double precision number. + /// A double precision number. + public static double Subtract(double a, double b) + { + return a - b; + } + + // Multiplies two intergers and returns the result + /// + /// Multiplies two integers and and returns the result. + /// + /// + /// The product of two integers. + /// + /// + /// + /// int c = Math.Multiply(4, 5); + /// if (c > 100) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to multiply doubles. + /// + /// + /// + /// An integer. + /// An integer. + public static int Multiply(int a, int b) + { + return a * b; + } + + // Multiplies two doubles and returns the result + /// + /// Multiplies two doubles and and returns the result. + /// + /// + /// The product of two doubles. + /// + /// + /// + /// double c = Math.Multiply(4.5, 5.4); + /// if (c > 100.0) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// See to multiply integers. + /// + /// + /// + /// A double precision number. + /// A double precision number. + public static double Multiply(double a, double b) + { + return a * b; + } + + // Divides an integer by another and returns the result + /// + /// Divides an integer by another integer and returns the result. + /// + /// + /// The quotient of two integers. + /// + /// + /// + /// int c = Math.Divide(4, 5); + /// if (c > 1) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// Thrown when is equal to 0. + /// See to divide doubles. + /// + /// + /// + /// An integer dividend. + /// An integer divisor. + public static int Divide(int a, int b) + { + return a / b; + } + + // Divides a double by another and returns the result + /// + /// Divides a double by another double and returns the result. + /// + /// + /// The quotient of two doubles. + /// + /// + /// + /// double c = Math.Divide(4.5, 5.4); + /// if (c > 1.0) + /// { + /// Console.WriteLine(c); + /// } + /// + /// + /// Thrown when is equal to 0. + /// See to divide integers. + /// + /// + /// + /// A double precision dividend. + /// A double precision divisor. + public static double Divide(double a, double b) + { + return a / b; + } +} +``` + +From your code you can generate a well detailed documentation website complete with clickable cross-references but then you're faced with another problem, your code has become hard to read. +This is going to be a nightmare for any developer who wants to contribute to this code, so much information to sift through. +Thankfully there's an XML tag that can help you deal with this: + +### <include> + +The `` tag lets you refer to comments in a separate XML file that describe the types and members in your source code as opposed to placing documentation comments directly in your source code file. + +Now you're going to move all your XML tags into a separate XML file named `docs.xml`, feel free to name the file whatever you want. + +```xml + + + + + The main Math class. + Contains all methods for performing basic math functions. + + + This class can add, subtract, multiply and divide. + These operations can be performed on both integers and doubles. + + + + + Adds two integers and and returns the result. + + + The sum of two integers. + + + + int c = Math.Add(4, 5); + if (c > 10) + { + Console.WriteLine(c); + } + + + Thrown when one parameter is max + and the other is greater than 0. + See to add doubles. + + + + An integer. + An integer. + + + + Adds two doubles and and returns the result. + + + The sum of two doubles. + + + + double c = Math.Add(4.5, 5.4); + if (c > 10) + { + Console.WriteLine(c); + } + + + Thrown when one parameter is max + and the other is greater than 0. + See to add integers. + + + + A double precision number. + A double precision number. + + + + Subtracts from and returns the result. + + + The difference between two integers. + + + + int c = Math.Subtract(4, 5); + if (c > 1) + { + Console.WriteLine(c); + } + + + See to subtract doubles. + + + + An integer. + An integer. + + + + Subtracts a double from another double and returns the result. + + + The difference between two doubles. + + + + double c = Math.Subtract(4.5, 5.4); + if (c > 1) + { + Console.WriteLine(c); + } + + + See to subtract integers. + + + + A double precision number. + A double precision number. + + + + Multiplies two integers and and returns the result. + + + The product of two integers. + + + + int c = Math.Multiply(4, 5); + if (c > 100) + { + Console.WriteLine(c); + } + + + See to multiply doubles. + + + + An integer. + An integer. + + + + Multiplies two doubles and and returns the result. + + + The product of two doubles. + + + + double c = Math.Multiply(4.5, 5.4); + if (c > 100.0) + { + Console.WriteLine(c); + } + + + See to multiply integers. + + + + A double precision number. + A double precision number. + + + + Divides an integer by another integer and returns the result. + + + The quotient of two integers. + + + + int c = Math.Divide(4, 5); + if (c > 1) + { + Console.WriteLine(c); + } + + + Thrown when is equal to 0. + See to divide doubles. + + + + An integer dividend. + An integer divisor. + + + + Divides a double by another double and returns the result. + + + The quotient of two doubles. + + + + double c = Math.Divide(4.5, 5.4); + if (c > 1.0) + { + Console.WriteLine(c); + } + + + Thrown when is equal to 0. + See to divide integers. + + + + A double precision dividend. + A double precision divisor. + + + +``` + +In the above XML each member's documentation comments appears directly inside a tag named after what they do; you can choose your own strategy. +Now that you have your XML comments in a separate file let's see how your code can be made more readable using the `` tag: + +```csharp +/* + The main Math class + Contains all methods for performing basic math functions +*/ +/// +public class Math +{ + // Adds two integers and returns the result + /// + public static int Add(int a, int b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Adds two doubles and returns the result + /// + public static double Add(double a, double b) + { + // If any parameter is equal to the max value of an integer + // and the other is greater than zero + if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0)) + throw new System.OverflowException(); + + return a + b; + } + + // Subtracts an integer from another and returns the result + /// + public static int Subtract(int a, int b) + { + return a - b; + } + + // Subtracts a double from another and returns the result + /// + public static double Subtract(double a, double b) + { + return a - b; + } + + // Multiplies two intergers and returns the result + /// + public static int Multiply(int a, int b) + { + return a * b; + } + + // Multiplies two doubles and returns the result + /// + public static double Multiply(double a, double b) + { + return a * b; + } + + // Divides an integer by another and returns the result + /// + public static int Divide(int a, int b) + { + return a / b; + } + + // Divides a double by another and returns the result + /// + public static double Divide(double a, double b) + { + return a / b; + } +} +``` + +An there you have it, our code is back to being readable and no documentation information has been lost. + +The `filename` attribute represents the name of the XML file containing the documentation. + +The `path` attribute represents an [XPath](https://msdn.microsoft.com/en-us/library/ms256115(v=vs.110).aspx) query to the `tag name` present in the specified `filename` + +The `name` attribute represents the name specifier in the tag that precedes the comments + +The `id` attribute which can be used in place of `name` represents the ID for the tag that precedes the comments + +### User Defined Tags + +All the tags outlined above represent those that are recognized by the C# compiler. However, a user is free to define their own tags. +Tools like Sandcastle bring support for extra tags like [``](http://ewsoftware.github.io/XMLCommentsGuide/html/81bf7ad3-45dc-452f-90d5-87ce2494a182.htm), [``](http://ewsoftware.github.io/XMLCommentsGuide/html/4302a60f-e4f4-4b8d-a451-5f453c4ebd46.htm) +and even support [documenting namespaces](http://ewsoftware.github.io/XMLCommentsGuide/html/BD91FAD4-188D-4697-A654-7C07FD47EF31.htm). +Custom or in-house documentation generation tools can also be used with the standard tags and multiple output formats from HTML to PDF can be supported. + +## Recommendations + +Documenting code is definitely a recommended practice for lots of reasons. However, there are some best practices and general use case scenarios +that need to be taken into consideration when using XML documentation tags in your C# code. + +* For the sake of consistency all publicly visible types and their members should be documented. If you must do it, do it all. +* Private members can also be documented using XML comments, however this exposes the inner (potentially confidential) workings of your library. +* In addition to other tags, types and their members should have at the very least a `` tag because its content is needed for intellisense. +* Documentation text should be written using complete sentences ending with full stops. +* Partial classes are fully supported and documentation information will be concatenated into one. +* The compiler verifies the syntax of ``, ``, ``, ``, `` and `` tags. +It validates the parameters that contain file paths and references to other parts of the code. diff --git a/docs/csharp/index.md b/docs/csharp/index.md index c02ef5d6aad09..6105cb483c00a 100644 --- a/docs/csharp/index.md +++ b/docs/csharp/index.md @@ -33,4 +33,3 @@ Or, check out the [C# Concepts](concepts.md) to learn the features of the C# lan ## Experienced C# developers If you've used C# before, you should start by reading what's in the latest version of the language. Check out [What's new in C# 6](csharp-6.md) for the new features in the current version. Then, explore the [C# Concepts](concepts.md) where you want more depth. - \ No newline at end of file diff --git a/docs/toc.md b/docs/toc.md index ce13edb056150..e75a55dbfb420 100644 --- a/docs/toc.md +++ b/docs/toc.md @@ -55,7 +55,7 @@ #### [Summary](csharp/expression-trees-summary.md) ### [🔧 Native interoperability](csharp/interop.md) ### [🔧 Reflection & code generation](csharp/reflection.md) -### [🔧 Documenting your code](csharp/codedoc.md) +### [Documenting your code](csharp/codedoc.md) ## [🔧 Syntax Reference](csharp/syntax.md)