[Wind yuchong] C # code annotation specifications and document generation in the unity3d tutorial book

OriginalArticleIf you need to reprint, please note: Reprinted from Fengyu Chong unity3d tutorial Institute  C #CodeAnnotation specification and document generation
In the development of unity3d games using C #, good comments and documents can make development more efficient and organized. This lecture is divided into two parts: I. Write notes 2: generate documents
 Write comments
Development comments are // help to expand the code
Note: // help use the code
Development Notes: Assists with development and comments on subsequent development of Code such as variables or functions. For example, you have defined a private int coins variable and do not intend to allow external access to the variable. However, some tips are required during the development process. // Quantity of gold coins Private int Coins ;
Note: It is used for help. It is mainly used to annotate the call of Code such as variables or functions. For example, the preceding coins variable is intended to allow external access. The code is public Int. Coins; input before this code /// Mono automatically generates the following comments based on the variable name. Summary is a summary of the code below.

 

1. /// <Summary>
2. /// The coins.
3. /// </Summary>
4. Public IntCoins;

You can add comments by yourself, as shown in figure

1. /// <Summary>
2. /// Total coins
3. /// </Summary>
4. Public Int Coins;

Or input text by line. <para> </para> indicates a line.

 

1. /// <Summary>
2. /// <Para> Coins </Para>
3. /// <Para> It can be used as money. </Para>
4. /// </Summary>
5. Public IntCoins;

Functions are also written in the same way. The following functions are available:

 

1. Public VoidUsecoins (IntNumber)
2. {
3. }

Enter // before the Function /// .  < Param   Name = 'Number'> </param> indicates a parameter.

 

1. /// <Summary>
2. /// Uses the coins.
3. /// </Summary>
4. /// <Param Name= 'Number'>
5. /// Number.
6. /// </Param>
7. Public VoidUsecoins (IntNumber)
8. {
9. }

The advantage of this writing is: 1. A comment is displayed during the call, as shown below:

2. automatically generate documents based on the annotations in this format    Generate document After the code is annotated in the format described above, the document can be automatically generated. In the past two days, Feng yuchong sought the best way to generate the unity3d Code help document.

We tried three methods:
(1) Mono: the steps provided by mono are too cumbersome, and you need to run the command. Give up.
(2) Visual Studio + sandcastle Help File Builder
This method is fine, and the steps are a little complicated, and Sandcastle Help File builder has many disadvantages, for example, the class must be in the namespace (unity3d 4.0 or above to support the inheritance function of monobehaviour in the namespace), slow, and incomplete functions.
Practice:
  Drag the code and unityengine. dll libraries into Visual Studio and use vs build.
  Then, use sandcastle Help File builder to load the generated XML and generate the document.
(3) doxgen: charts are supported. classes can be excluded from namespaces. JS is not supported. Cross-platform.
Finally, Feng yuchong found the most suitable document generation tool for unity3d-doxgen.

                                   Doxgen usage

Open after download,
(1) set as shown in Figure

(2) set the chart as follows.

(3) Remove the path prefix. (The path is displayed in the lower left corner of the document page)
Example:
Code pathD: \ My Documents ents \ namespacetest \ assets \ scripts \ Gui
Enter D:/My Documents documents/namespacetest/assets/scripts in the cropping path.

(4) generate a document.
(5) view the document.

You can click the show HTML output button or directly open the local webpage. Saved folder-> HTML folder-> index.html

(6) click File> Save to save the configuration file. This file can be used to read configurations, or cross-platform.

PS: the usage of doxygen in Mac OSX is similar.

Final effect: