C # document automation
This article mainly refers to Chapter 15 of "Inside C #".
Familiar with Java's programmers know that there is a "document comment" in Java. After using this annotation, use the appropriate command, we can get document descriptions related to the code. Today, C # in the world of .NET also provides the same functionality. If combined with the corresponding tool, it can also generate a beautiful Web style document.
Document automation initial:
The symbol corresponding to the document comment in the C # is: ///. But light uses it or does not generate code documentation for us, but also use special tags. These markers are actually an XML tag, most commonly used,
///
/// a Method with a string array param.
///
Public void koo (String [] ss) {}
However, not all document comments and these tags of local compilers will generate documents for us, which will also see if these tags are associated with some code structures. E.g:
///
/// Do not produce this line
///
There is no documentation. These code structures must be: Class, Struct, Enum, Method, Property, Field, INDEXER, DELEGATE, or EVENT.
Generate a document command
- Command line: CSC / DOC: ... .xml ... ..cs;
- If you use vs.net, then: Project -> Properties -> Configuration Properties -> Generate -> Output -> XML Document File (Fill in the file name and path here);
- To generate a web annotation: Tool -> Generate Note Web .......
Output document type descriptor
character
description
N
Namespace
T
Type: Class, Interface, Struct, ENUM, DELEGATE
Fly
Field
P
Property (including Indexers or other indexed property)
M
Method (including constructors and operators)
E
Event
!
Error: The compiler cannot resolve this element.
An example of an output file annotation:
An enum field.
An Enum Type.
XML document tag.
mark
description
Indicates this line annotation to be identified as CODE
Indicates multi-line annotations identified as CODE
Often use to give examples of how to use certain members.
Indicates which exceptions will be thrown in a member, often with the CREF property.
Indicates in which files are in the comments, and location.
Used to define the header, often use
Internal use, such as
Describe the properties of the parameters, the compiler will check the legality of the parameters. If not, it will be generated in the document!
Similar to .
Indicates the security of code access for members.
Used to describe Class or other types of descriptive text, do not involve specific details (if so, use
Describe the return value of the method or function.
Specify a link.
Specifies the text to appear in the SEE AlSo section.
Type descriptive text. It will be used by VS.NET built-in IntelliSense and displayed in the corresponding type. (Ie in vs.net "." "Prompts that appear)
Describe the properties.
The properties of the above markings are marked.
mark
description
CREF
Can be used for any tag to provide a reference for a code element. The compiler will check if this code element exists, if there is no existence, use it in the document! ID.
Name
Used in or
Mark use example
1. tag
///
/// a Method with a string array param.
///
///
Public void koo (String [] ss) {}
2.
///
/// a nonvoid method.
///
///
Public int NOO () {RETURN 0;
3.
///
///
/// throws a fileioException when ...
///
///
Public void foo () {}
4. , and
///
///
///
Public void hoo () {}
///
/// The joo method.
///
///
///
/// public static void
Main
()
/// {
/// console.writeLine (class1.joo ());
///}
///
/// ///
///
Public static int joo () {return 0;}
5.
grammar:
///
Class class1 {
Public static void
Main
() {}
}
Supporting.xml
The Summary for this Type.
Another Type Description.
6. Tag
grammar:
///
///
///
///
///
///
///
///
///
///
Static void
Main
(String [] ARGS) {}
expansion
Since the document generated is an XML file, we have made our handling of it. If you can define an XLS to make it generate a document that meets our needs, such as HTML, Word, and more. For HTML, C # compiler has built-in support. We can use standard HTML tags to expand it. However, since XML is Well-Formed, it is necessary to use it as an XML effective element for some HTML elements without symbol. Such as
, corresponding to it.
to sum up
