C#. NET prerequisite tools GhostDoc for code generation annotation Documents

generate a comment document for code using GhostDoc

"Turn from www.bitsCN.com"

Introduced:
GhostDoc is a free plugin for Visual Studio to help developers write annotated documents in XML format.
Document annotations in XML format in C # are much more beneficial: Visual Studio displays these annotation content in many places (for example, the editor's ToolTip or Object Browser). Other tools, such as NDoc or Microsoft's documentation tool Sandcastle, can also be used to generate a good looking help file. All this makes XML-formatted annotations look beautiful-but unfortunately, you first have to write a lot of simple, tedious annotations.
What GhostDoc can do.
GhostDoc installs a new command for the C # code Editor in Visual Studio. When editing a source file, simply place the cursor inside the method or property to which you want to add the document, and then invoke the command by using the hotkey (default ctrl+shift+d) or the document this menu item in the right-click menu, GhostDoc inserts an XML-formatted comment. You might think of a similar effect when you type "///" in front of a method or property, but the latter can only create a blank annotation construct, while GhostDoc can generate most of the useful annotations.
If your class member is a member that implements an interface or overrides a base class, GhostDoc uses the existing document, regardless of where those interfaces or base classes come from. So you can reuse a lot of Microsoft-written documents-whether you think about how to add annotations to the GetEnumerator () method when implementing the Ieumerable interface.

If no existing documents are available, GhostDoc will try to "guess" how to generate comments for you. The idea may seem a little strange at first, but under certain conditions (which will be mentioned later) GhostDoc is doing very well. Sometimes it's "guessing" the results are not accurate, even some funny, but on average, it is better to modify these generated documents than the full manual to save a lot of time.
GhostDoc In fact does not understand English, then why the document produced by it is often quite satisfactory. The rationale is quite simple, GhostDoc assumes that your code complies with the Microsoft Library Developer Design specification:
<!--[if!supportlists]--><!--[endif]-->
Your code uses Pascal or camel nomenclature to name identifiers that consist of multiple words
Your method name usually starts with a verb.
You do not use abbreviations in identifiers
<!--[if!supportlists]--><!--[endif]--><!--[if!supportlists]--><!--[endif]-->
If you can follow these rules (for example, by using ClearCache () instead of CLRCCH (), and using some interpreted identifier names, then GhostDoc can come in handy, dividing the identifiers into several words, combining them to generate annotations, which may not be perfect, But give you a good start to the document.
The generation of text uses customizable rules and templates, in addition to built-in rules, you can define new custom rules to extend or replace existing rules (give your custom rules a higher priority or disable built-in rules).

As mentioned above, GhostDoc does not understand English, but it tries to use some mechanism to improve the quality of the generated annotations:

<!--[if!supportlists]--><!--[endif]-->
The processing mechanism of verbs (GhostDoc assumes the first word of the method name as a verb):add->adds,do->does,specify->specifies;
The sort organization mechanism of "of": ColumnWidth-> Width of the column.
Special combinations of special adjectives: for example,,maximumcolumnwidth-> "Maximum width ofthe column" Instead of "width of the Maximum column"
Automatic detection of the constants consisting of acronyms and a list of other acronyms
Use a list of words to decide when not to use the "the": AddItem->adds the item, Buildfromscratch-> builds from scratch
<!--[if!supportlists]--><!--[endif]--><!--[if!supportlists]--><!--[endif]--><!--[if !supportlists]--><!--[If!supportlists]--><!--[endif]-->
Here are some examples of applying GhostDoc:
<summary>
Determines the size of the page buffer.
</summary>
<paramname= "Initialpagebuffersize" >initial size of the pagebuffer.</param>///<returns></ Returns>
public int determinepagebuffersize (intinitialpagebuffersize)
{
return 0;
}

<summary>
Adds the specified item.
</summary>
<param name= "Item" >Theitem.</param>
public void Add (string item)
{
Does something
} bitscn.com

<summary>
Appends the HTML text.
</summary>
<param name= "Htmlprovider" >the htmlprovider.</param>
public void Appendhtmltext (Ihtmlprovider htmlprovider)
{
} is not surprisingly accurate.
The quality of the ghostdoc generated annotations depends to a large extent on the quality of the identifier naming,

So long-term use of GhostDoc will also allow you to learn to write consistent and self explanatory identifiers, a delight.

GhostDoc can't do anything.

GhostDoc is very powerful, but it cannot expect too much of it. The way it generates annotations may not fit well with your personal annotation style. GhostDoc can also not generate annotations for the entire code file at once, only to generate comments for one member at a time--ghostdoc so designed, because you always need to check every comment it generates anyway.

GhostDoc configuration:

Select Tools->ghostdoc->configure GhostDoc in the Visual Studio menu bar.

It contains the following property pages:

<!--[if!supportlists]--><!--[endif]--><!--[if!supportlists]--> bitscn.com

Rules: Modifying, deleting, adding a text generation rule

Acronyms: Specifies which words are treated as acronyms

"Of the" reordering: Specifies the word that triggers the reordering behavior

"No" Words: Specify which words are not used before "the"

Options: Configure additional options for GhostDoc

Download Link:

Http://submain.com/download/GhostDoc_v2.5.zip

using GhostDoc to implement custom annotations

Using GhostDoc can help us generate a more complete code comment, if the variable naming specification, just press the CTRL+SHIFT+D (the default hotkey), the automatically generated comments by it has been fully able to express the purpose of our creation method or property, Instead of requiring us to manually modify the annotations. In addition to these, its strength lies in its availability. We can definitely customize the annotation instructions we need through the rule definition. The following illustration illustrates how to customize annotations.

Under the VS. Tools menu, select the next level of GhostDoc menu item to open the GhostDoc configuration panel

Select method to add a rule by clicking the Add button.

When you select the Summary field, click on the last button to configure the annotation template, "Go from www.bitsCN.com"

Double-click to select a macro variable:

All the way OK back.
Write a method to test ... The cursor is moved to the location of the method name and the ctrl+shit+d is not valid and will not be generated in another location.
The same method can define personality for attributes, parameters, and export the current configuration for use after the next reload.

GhostDoc Installation and configuration

1, GhostDoc1.2.1 Introduction

GhostDoc is an XML document annotation builder based on Visual Studio that can help you automatically generate a lot of annoying, similar descriptions, compared to NDoc.

China Network Management Forum Bbs.bitsCN.com

2, installation (for VS2005)

Make sure that visual Studio2005 is turned off before you install and double-click ghostdoc2.1.1.msi for installation

Feedom.net

Click "Next":

Select "I Agree" and click "Next":

In

Select the path to install and click "Next":

Click "Next" to start the installation:

In

After the installation is complete, a window with the following image appears.

Click "Close" to complete the installation: China Network management Forum Bbs.bitsCN.com

3, Configuration 2.1. Initial setup

Open Visual Studio 2005, which appears as a diagram dialog box, as follows:

Here you can set the hotkey, click "Assign", if you do not know what to set the hotkey, or to set the hotkey is not in the Drop-down menu, click "Skip", and then set. Click "Skip" here, the following figure: Net

If it is the first time to install GhostDoc, click "Create";

If you want to load an existing structure, click "Import" (click "Create" here). The following window appears:

Click Finish to enter the Visual Studio 2005 interface, as shown below:

A "ghostdoc" option appears in the Drop-down menu of tools, as shown in the following figure:

Bitscn_com

The "Document This" command appears in the right menu, as shown in the following figure:

Feedom.net

2.2, the GhostDoc configuration

In the Visual Studio2005 menu bar, select Tools | ghostdoc| Configure GhostDoc ", the pop-up dialog box is shown below:

Property Pages contained in:

1. Rules modification, delete, add text generation rule

2. Acronyms specifies which words to use as acronyms

3. "The" reordering specifies the word that triggers the reordering behavior

4. "No" Words specify which words are not used before "the"

5. Options configuration ghostdoc Other option

ghostdoc automatically generate XML annotations

To quickly add XML annotations to a Visual Studio project

The Microsoft®.net Framework simplifies the task of recording classes, methods, properties, and events through XML annotations. An XML annotation is a special XML tag embedded in a source code comment that provides related metadata for a class and its members. During compilation, this metadata is converted from Visual studio® to a stand-alone XML file, and then converted to a Help file by using a tool such as Microsoft Sandcastle Project.

GhostDoc will automatically generate XML annotations (click the image for a larger view)

When an XML annotation assists in automatically converting a source code comment to an RTF help document, it is still necessary to write the comment text, which is a job that is exhausting to many developers. Why not use automation to speed up the creation of these annotations? This is exactly what GhostDoc 1.9.5 is trying to achieve.

GhostDoc is a free Visual Studio add-in, created by Roland Weigelt, to assist in writing XML annotations. Once the GhostDoc is installed, it is easy to automatically generate XML annotations simply by using it to point to points. For example, to add an XML annotation to a method, simply right-click in the method and select the Document this option from the context menu.

GhostDoc automatically generates XML comment text for the method based on its type, parameter, name, and other contextual information.

If you are building a document in the. NET Framework for a property or method that uses a type, GhostDoc will use a document that Microsoft has written for that type. If you use Pascal casing or Camel case, GhostDoc splits the name into several words and analyzes the individual words to generate the document. All document logic is processed according to the GhostDoc generation rules. You can customize these built-in rules, or you can add new rules. You can also export these rules for use on other computers.

In addition to the simplest members, you cannot rely entirely on GhostDoc to write XML annotations for you. GhostDoc automatically generated comments are only recommended and need to be reviewed by developers. In any case, GhostDoc is a worthwhile note-writing plug-in that can save a lot of time.