Sandcastle Kingdoms Free Download Document Your C# Code with XML Comments
Total Page：16
File Type：pdf, Size：1020Kb
sandcastle kingdoms free download Document your C# code with XML comments. 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 use IntelliSense to show quick information about types or members. Additionally, the XML file can be run through tools like DocFX and Sandcastle to generate API reference websites. XML documentation comments, like all other comments, are ignored by the compiler. You can generate the XML file at compile time by doing one of the following: If you are developing an application with .NET Core from the command line, you can add a GenerateDocumentationFile element to the <PropertyGroup> section of your .csproj project file. You can also specify the path to the documentation file directly using DocumentationFile element. The following example generates an XML file in the project directory with the same root filename as the assembly: This is equivalent to the following: If you are developing an application using Visual Studio, right-click on the project and select Properties . In the properties dialog, select the Build tab, and check XML documentation file . You can also change the location to which the compiler writes the file. If you are compiling a .NET application from the command line, add the DocumentationFile compiler option when compiling. XML documentation comments use triple forward slashes ( /// ) and an XML formatted comment body. For example: 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: The sample library supports four major arithmetic operations ( add , subtract , multiply , and divide ) on int and double data types. 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> The <summary> tag adds 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. The <summary> tag is important, and we recommend that you include it because its content is the primary source of type or member information in IntelliSense or an API reference document. <remarks> The <remarks> tag supplements the information about types or members that the <summary> tag provides. In this example, you'll just add it to the class. <returns> The <returns> tag describes the return value of a method declaration. As before, the following example illustrates the <returns> tag on the first Add method. You can do the same on other methods. <value> The <value> tag is similar to the <returns> tag, except that you use it for properties. Assuming your Math library had a static property called PI , here's how you'd use this tag: <example> You use the <example> tag to include an example in your XML documentation. This involves using the child <code> tag. The code tag preserves line breaks and indentation for longer examples. You use the <para> tag to format the content within its parent tag. <para> is usually used inside a tag, such as <remarks> or <returns> , to divide text into paragraphs. You can format the contents of the <remarks> tag for your class definition. Still on the topic of formatting, you use the <c> tag for marking part of text as code. It's like the <code> tag but inline. It's useful 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. <exception> By using the <exception> tag, you let your developers know that a method can throw specific exceptions. Looking at your Math library, you can see that both Add methods throw an exception if a certain condition is met. Not so obvious, though, is that integer Divide method throws as well if the b parameter is zero. Now add exception documentation to this method. 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. The <see> tag lets you create a clickable link to a documentation page for another code element. In our next example, we'll create a clickable link between the two Add methods. 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 <seealso> tag in the same way you do the <see> tag. The only difference is that its content is typically placed in a "See Also" section. Here we'll add a seealso tag on the integer Add method to reference other methods in the class that accept integer parameters: 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 <param> tag to describe a method's parameters. Here's an example on the double Add method: The parameter the tag describes is specified in the required name attribute. <typeparam> You use <typeparam> tag just like the <param> tag but for generic type or method declarations to describe a generic parameter. Add a quick generic method to your Math class to check if one quantity is greater than another. <paramref> Sometimes you might be in the middle of describing what a method does in what could be a <summary> tag, and you might want to make a reference to a parameter. The <paramref> tag is great for just this. Let's update the summary of our double based Add method. Like the <param> tag, the parameter name is specified in the required name attribute. <typeparamref> You use <typeparamref> tag just like the <paramref> tag but for generic type or method declarations to describe a generic parameter. You can use the same generic method you previously created. You use the <list> tag to format documentation information as an ordered list, unordered list, or table. Make an unordered list of every math operation your Math library supports. You can make an ordered list or table by changing the type attribute to number or table , respectively. <inheritdoc> You can use the <inheritdoc> tag to inherit XML comments from base classes, interfaces, and similar methods. This eliminates unwanted copying and pasting of duplicate XML comments and automatically keeps XML comments synchronized. Put it all together. If you've followed this tutorial and applied the tags to your code where necessary, your code should now look similar to the following: From your code, you can generate a detailed documentation website complete with clickable cross-references. But you're faced with another problem: your code has become hard to read. There's so much information to sift through that this is going to be a nightmare for any developer who wants to contribute to this code. Thankfully there's an XML tag that can help you deal with this: <include> The <include> 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. In the above XML, each member's documentation comments appear 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 by using the <include> tag: And there you have it: our code is back to being readable, and no documentation information has been lost. The file attribute represents the name of the XML file containing the documentation. The path attribute represents an XPath query to the tag name present in the specified file . 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 <event> and <note>, and even support documenting namespaces. 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 recommended for many reasons. What follows are some best practices, general use case scenarios, and things that you should know when using XML documentation tags in your C# code. The Far Kingdoms: Forgotten Relics. Test your solitaire skill by finding the stolen relics across 4 kingdoms in this challenging solitaire game, The Far Kingdoms: Forgotten Relics.