Compilation of smartdoc (yuidoc) annotations

This section describes the JS documentation and demo design tools. Smartdoc uses the yuidoc engine, so the annotation rules are the same. First, let's briefly introduce the compilation of yuidoc annotations.

 

Writing comments is a very heavy physical activity, and many programmers are reluctant to do this, but in the process of writing, you will notice a lot of details and consider some unexpected points, you will find many problems and optimization points.

 

In order to improve efficiency, we should plan the code from the beginning, organize documents, modules, and code, and comprehensively consider unit tests, comments, and demos for effective reuse;

Of course, the use of smartdoc in any case is much faster than the independent development documentation and demo.

 

Annotation mark

 

Start with/**, */, and end with @ specified type

//第一种方式/**
　 desc  @....  @....*///第二种方式/**
 * desc * @.... * @....*/

* If the second method is different from the first method, the content of the comment will be aligned according to the position of *. The two methods can be used in combination but are not recommended, making the layout very difficult.

* The comments can be empty and do not need to be followed by the Code. yuidoc only scans/**... */content descriptions;

* DESC can use HTML

* Supports markdown.

* You can enter the API link crosslink in the following format:{{# Crosslink "module. Class/method" }{{/ crosslink }}For example, see @ Class description.

 

Master tag

 

Tag Name	Note	Effect	Detailed description
@ module	/*** this is my example module * @ module examplemodule * @ example ** var bar; **/		module tag; All @ classs after the tag are classified under the module; it is best to define a module in a JS file. multiple modules in a file may cause frequent yuidoc scans; if other JS files expand this module, use the @ submodule related labels: @ main, @ submodule, @ example, @ namespace, @.
@ class	/*** superclass description. This is a second line too. ** @ constructor * @ Class superwidget * @ extends widget * @ namespace mywidget * @ example ** var bar; **/		class tag; the @ method, @ property, @ event, @ attribute if it is inherited, add @ extends/@ extensionfor in @ class, if you want to use @ example, add @ constructor related labels: @ constructor, @ extends, @ extensionfor, @, @ module, @ namespace, @ static, @ uses.
@ method	/*** overwritten method see {# crosslink "mywidget. superwidget "}}< BR >{{/crosslink }}* also see {{# crosslink" mywidget. superwidget/mymethod "}}< BR >{{/crosslink} * this is also a test * @ method gettargets2 * @ example ** var bar; **/		class method label; description method it is often said that the method is not under the @ class, therefore, to specify a specific @ class, use @ for; parameter description using @ Param return value using @ return, if the returned object is a class (that is, this), use the @ chainalbe related Tag: @ chainable, @ class, @ constructor, @ for, @ Param, @ return, @ static, @ async, @ protected, @ private, @ final.
@ Method Example 2	/** Add product method, register @ Method Add @ Param {string} name in the factory Product Name @ Param {object} item product feature @ Param {string} [Parent] parent class name, register the product name @ return {object | Klass} in the factory and return the created product @ example // a widget factory var widgetfactory = ST. factory ({// factory name: 'wdigetfactory ', // factory type: 'class', // base class Object base: {}});....... */
@ Property	/*** Override property * @ property name2 * @ Type string */		Basic class attributes; Define simple type attributes   Related labels: @ Type, @ for, @ default, @ required, @ optional, @ readonly, @ static, @ protected, @ private, @ final.
@ Attribute	/*** Override attribute * @ attribute focused3 * @ required */focused3 :{...},		Complex attributes of a class; Mainly defines complex attributes such as objects   Related labels: @ Type, @ for, @ default, @ required, @ optional, @ readonly, @ static, @ protected, @ private, @ final.
@ Event	/*** Override event * @ event init2 * @ Param {object} opt options * @ example * var A = ''; */init2: function (OPT ){}		Class event definition; Similar to @ method, it is classified as an event type.   Related labels: @ Chainable, @ class, @ constructor, @ for, @ Param, @ return, @ static, @ async, @ protected, @ private, @ final, @ bubbles.

 

Secondary tag

 

Tag Name	Note	Description
@ Submodule	/*** Provides y. JSON. parse method to accept JSON strings and return native * JavaScript objects. ** @ module JSON * @ submodule JSON-Parse * @ for JSON * @ static */	Sub-module; As an extension of @ module, the extension is usually used in many @ class files that are not in the same @ module.
@ Main	/*** The JSON module adds support for serializing JavaScript... ** @ module JSON * @ main JSON * @ Class JSON * @ static */	Mark the main module; It is mainly used as a definition directory; If @ module and main are defined at the same time as @ class, JSON and class JSON will share the same annotation information after being generated.
@ Namespace	/*** Subclass description. ** @ constructor * @ namespace mywidget * @ Class subwidget2 * @ extends accordion */	Namespace; In this example, the final @ Class path is displayed as mywidget. subwidget2
@ Extends	Same as above	Inherit tags; used as inheritance
@ Extension @ Extensionfor	Omitted	Extension tag; opposite to @ extends, class Extension
@ Constructor	Same as above	Constructor label; @ class dedicated; Note: If you want to use @ example, you must have @ constructor.
@ Static		Static ID
@ Final		Constant, non-variable identifier
@ Readonly		Read-Only
@ Optional		Optional
@ Required		Required
@ Param	/*** Update operation interface ** [interface method] *** @ method update * @ Param {object} op parameter; * @ Param {object} op. filter filter * @ Param {object} op. data Update Data * @ Param {object} op. method of execution after success is successful * @ Param {object} op. method * @ return {object} operation result after error failure */	Parameter tag; @ method, @ Constructor's @ class and @ event are available @ Param: You can set sub-@ Param, but it can be up to three levels. Sub-parameters must be named using Param. childparam;
@ Return		Return Value
@ Chainable		When the returned value is your own class Object (that is, this), use
@ Type	/*** ...... * @ Property usenativeparse * @ type boolean * @ default true * @ static */	Type tag; used in @ porperty and @ attribute
@ Deault		Default Value settings
@	/*** Some method 'bar' * disconnected from * its class 'farawayclass'... ** @ method bar * @ for farawayclass */ /*** Some inner class 'foo'... ** @ Class Foo * @ for outerclass */	Both methods, but the target is @ Class 1. Specify the @ Class option, @ method, @ porperty, @ attribute, and @ event 2. Set the inner class of @ class, which is used in @ class.
@ Private		Private ID
@ Protected		Protection ID
@ Async		Asynchronous Method ID
@ Uses	/*** @ Class panel * @ constructor * @ extends widget * @ uses widgetautohide * @ uses widgetbuttons ...*/	Mix into the mix tab; you can define multiple
@ Requires	/*** @ Module event-simulate * @ requires event */	Tag of the module dependency. It indicates the modules used by the module.
@ Since	/*** @ Since 3.4.0 */	Indicates the version from which this function is added
@ Example	/*** UI test class; * @ Class UI * @ constructor * @ content {string} type content * @ example * <HTML> * <Div id = 'Container'> HTML render </div> * </ HTML> ** <SCRIPT> * var UI = new UI ("UI test "); * </SCRIPT> */	Sample Code; two modes: 1. js code, which is directly written into JS 2. html and JS, including <HTML>

 

End

There are so many commonly used,For more information, see yuidoc annotations;

Most of the examples in this article are in the input directory of the smartdoc code, which can be generated by running the instructions;

Compilation of smartdoc (yuidoc) annotations