Flex help document creation (asdoc-Note 1)

I have previously written a help document for packaging my own with asdoc, and then I wrote how to change the packaged HTML document to the chm format, note some parameters when using asdoc to write comments.

First, let's look at a class without any comments. The class is defined as follows:

package moter{    import flash.events.EventDispatcher;    [Event(name="succeedCallback", type="flash.events.Event")]        public class Demo extends EventDispatcher    {        private static const static_const_private:int=0;        protected static const const_protected:String="";        public static const const_public:Boolean=true;                    private static var static_private_variable:int;        protected static var static_protected_variable:String;        public static var static_public_variable:Boolean;                private var _private_variable:int;        protected var protected_vairable:String;        public var public_variable:Boolean;                private const const_private:int=0;        protected const const_protected:String="";        public const const_public:Boolean=true;                public function Demo(str:String)        {        }                public function get private_variable():int        {            return _private_variable;        }            public function set private_variable(value:int):void        {            _private_variable = value;        }        private static function static_private_method():void        {            }        protected static function static_protected_method():void        {        }        public static function static_public_method():void        {        }                public function public_method():void        {        }        protected function protected_method():void        {        }        private function private_method():void        {        }    }}

It contains almost all class-related definitions and runs asdoc to generate such documents (this step is detailed in the flex help document creation (asdoc-html ).

Dream Catcher (pen name) found that the static public attributes of the generated documents will be organized together with the public attributes, and the static protected attributes will be organized together with the protected attributes; the same is true for the method. At the same time, private members are not reflected in the document. (Our so-called fields are actually marked by attributes, and the Set get attribute is also included in the attributes)

First, we generally describe the classes, members, and member functions of class files. So how should we write this attention description? If you want to add comments to the specified class, member attributes, and member functions, you can comment on the top of these declarations according to the following format attributes:

(In flash builder, press Ctrl + Shift + D to easily add asdoc comments)

(Note that there must be spaces between the comments and *. Otherwise, any text at the first position will be ignored)

(Note that my asdoc is written in Chinese through the company package. If you want it, you can leave a message)

Source code:

/*** Public field */Public var public_variable: Boolean;

Effect:

　　

In this way, after a document generation operation, we will find that the comments you add will have an additional line of explanatory text under the response class, attribute, or method. The content of the comment can be any character, or even be decorated with HTML tags. (The output is HTML, which can be described by HTML tags.) After the most common annotations are completed, let's talk about the tags that can be parsed by asdoc, we will discuss it one by one.

　　1. @ author User Name

This tag is used to mark the founder of the class. By default, the user name is set to your computer's user name (for example, administor) by using the shortcut key to generate the system. You can modify the user name in the following three steps for a document on the Internet:

Step 1: Open c: \ Program Files \ Adobe Flash Builder 4 \ flashbuilder. ini.

Step 2: Add the following line:-duser. Name = heguang.

Step 3: add any-vmargs statement, and the equal sign has no space.

But I tried it but it was useless. Instead, I had to modify the space of my flash builder, and an error occurred. Please let me know!

Source code:

/*** Instance class ** @ author liuyayun */public class demo extends eventdispatcher

Effect:

　　

The instance class can be displayed. The following mark cannot be displayed. It is estimated that it is used to mark it!

　　2. @ Param flag

@ Param mark is a comment mark for parameters in a function with parameters. You can use this tag to generate descriptions of corresponding parameters. The mark is written in the following format:

@ Param parameter name parameter description

It can be seen from the writing format that a tag corresponds to only one parameter in a method. If a method contains multiple parameters, you can use multiple @ Param statements to describe them. The following is an example:

Source code:

/*** Method Description * @ Param name first parameter description * @ Param age second parameter description */Public Function public_method (Name: String, age: number ): void {}

Effect:

　　

As shown in the example, the content written in the @ Param mark is written into the parameters column. The @ Param Tag feature is also mentioned in the official documentation that the written parameter name must correspond to the parameter name in the method signature. That is to say, if there are two parameters, they must be annotated according to the defined parameter order. I tried to annotate a method with two parameters instead of according to the signature definition, and found that the annotation became messy. At the same time, I tried to add some characters to the paramname part of @ Param, but the output parameter name will still be displayed according to the parameter name in the method. Therefore, we can draw a conclusion that paramname can be any name, but the annotation information must correspond to the parameters in the signature order, so that asdoc can correctly allocate the parameter name to the correct annotation.

 

Of course, I am not in favor of the parameter name method, because this will lead to bad habits, but also cause reduced readability of the program. Therefore, the parameter name should be used to write parameter comments.

　　3. @ example mark

@ Example: You can add a descriptive example for a class, method, or attribute to make your code easier to understand. The format is as follows:

@ Example descriptive text

<Listing version = "3.0">

Sample Code

</Listing>

From the format, we can see that the sample code is written in the <listing/> MARK (version = "3.0" may be dispensable, but only the version number). The following is an example to illustrate, take the public_method function as an example:

Source code:

/*** Method Description * @ Param name first parameter description * @ Param age second parameter description * @ example Description * <listing> * // initialize a demo object * vaR Demo: demo = new demo ("dream catcher"); * // call the method public_method * demo. public_method ("dream chasing", 22 );*... * </listing> */Public Function public_method (Name: String, age: Number): void {}

Effect:

　　

 

As you can see, the text after @ example is output under example. This text is used to describe the example. The code written in the <listing/> mark is placed in a gray rectangle. According to official help instructions, a horizontal scroll bar is displayed in a box, so when the content exceeds a certain length, a horizontal scroll bar is displayed. This is also verified by the pursuit of dreams. It is found that horizontal scroll bars can appear. The height is determined by the height of the content, but no vertical scroll bars will appear. Note that the for loop is easy to appear in the comments, so you cannot avoid using <or>. Our intention is to use comparison in the comments, but asdoc recognizes these as tags, in this case, an error occurs. My method is to mark "or" in Chinese as "less than or equal". Please tell me if you have other ways to learn from each other.

　　4. @ return mark

@ Return describes the return values of a method. That is to say, this tag is used for annotation in the method. The writing format is as follows:

@ Return description

The following is an example:

Source code:

/*** Get name * @ return name */Public Function getname (): String {return "dream chasing far ";}

Effect:

　　

Obviously, the type of the return value is not specified in @ return in the comment, but the type of the return value can be displayed in the generated document, this is actually the type that asdoc can automatically identify the method return value, so we do not need to specify it. If this tag is added to a method without a return value (that is, a method with a return value type of void), it will not work.

　　5. @ see Mark

@ See is used to generate a reference. In some cases, some classes, attributes, or methods are described or referenced elsewhere. In this case, we can use this tag to reference this example. The writing format is as follows:

@ See reference [description text]

Take the following example:

Source code:

/*** Get the name ** @ see myceshi # getnamebyid () [text description] * @ return returns the name */Public Function getname (): string {return "Dream tracing far ";}

Effect:

　　

, The getname method has an additional column. For more information, see (see also). In this column, the reference of the getname method just described is provided. Maybe you will ask how to write the reference part in the @ see Mark? In fact, the internal method of the reference class is implemented through the anchor, so the reference part is to fill in an anchor (if you want to reference the anchor of a page, if you learn HTML, you will know that it is using the # anchor name ). In fact, the method and attribute generated by asdoc have an anchor. The rule is that the anchor of the method is the method name () (must be enclosed in parentheses), and the anchor of the attribute is the attribute name.

If there are multiple reference references in a class, method, or attribute, we can use multiple @ see for reference, which is allowed in asdoc.

According to the Dream chaser summary, the reference parameters marked by @ see should be written (for classes, methods, and attributes respectively ):

Package path. Class Name

Package path. class name # method name ()

Package path. class name # attribute name

If it is a method in the class, you can omit the package path. Class Name section.

　　6. @ private tag

This tag is used when you do not want to disclose your category, method, or attribute to others. The document description for this part will not be generated in asdoc. The writing format is as follows:

@ Private

Source code:

　　

/*** @ Private * Get the name * @ see myceshi # getnamebyid () [text description] * @ return returns the name */Public Function getname (): string {return "Dream tracing far ";}

The method cannot be described after the document is generated. It is no longer reflected in the document.

These should be commonly used parameters. Other parameters can be summarized later!