Summary of Development of document generation software for Javascript

I have been working on JS document generation software recently.

Currently, jsdoc is the main open source project in this field. First, let's introduce the jsdoc itself. It is a document tool developed in Java (mainly JavaScript) to directly process strings. Because javscript is very flexible, JavaScript document generation is naturally less accurate and effective than Java and so on. Jsdoc itself requires that a large number of labels be used in annotations to tell the document generator that this is a class, attribute, method, or other type. In parsing jsdoc, variables are determined by context, for example, if you use @ class to identify a class, the @ method described below will be automatically processed as the class referred to by the previous @ class, which is totally ignored.CodeIts own logic.

Not to mention whether the jsdoc method is convenient and effective. In short, what I want to do is generate a document Tool Based on syntax analysis.

My goal is to generate a document that is completely object-oriented, that is, the highest level of the document is the namespace (package), the lower level is the class, and the lower level is the member.

1. Category of members. Which parent member does a variable belong to after it is defined? This is what must be analyzed in document analysis.

/**
* Convert the current value to a number.
*/
Boolean. Prototype. tonumber= Function(){
Return +This;
};
 

From this code, we can see that there is a tonumber member whose parent is boolean. Prototype. In this case, we can easily detect the member, but if we use another method, for example, the method in ext is:

/**
* Convert the current value to a number.
*/
Ext. Extend (Boolean. prototype ,{ Tonumber:Function(){
Return +This;
}});
 

This is very troublesome because of document analysis.ProgramThe Code cannot be executed. It certainly does not know the parent member of tonumber. Jsdoc uses the most parent member of the recently used @ class. However, this can easily lead to many incorrect members in @ class.

Finally, I used the scope analysis method. That is, a function call or function definition is used as a scope. Their previous @ class will be understood as the parent Member of the Members in this scope. That is, the code should be annotated as follows:

/**
* Convert the current value to a number.* @ Class Boolean
*/
Ext. Extend (Boolean. prototype ,{ Tonumber:Function(){
Return +This;
}});
 

@ Class Boolean is only valid for this function, that is, @ class only interprets adjacent scopes. Likewise:

/**
* Convert the current value to a number.* @ Class Boolean
*/
(Function (){  Function tonumber(){
Return +This;
}})();
 

Because this is a function definition, the parent Member of the function is also @ Class Boolean.

Of course, these are all unreasonable computations, which may lead to incorrect results. You can specify @ memberof to overwrite the automatically judged parent variable.

For @ Class C, the Member is interpreted as C. Prototype. P.

For @ namespace C, or member @ static, it is interpreted as C. P

2. It has the ability to identify inheritance and prototype.

For example, A. Prototype = new B is a typical inheritance code.

You can perform prototype operations by running a simulation.

3. Based on my experience in writing JavaScript and referring to jsdoc, I decided to use the following system labels, which will make great contributions to document generation.

Global tag

Global tags are mainly used to describe the entire project or file. Generally, global labels can only be used at the top of a file.

• @ Projectdescription description of the current project
• @ Author of summary code
• @ Lisense summary code protocol
• @ Version the version of the summary code
• @ Fileoverview description of the current Summary File
• @ File summary indicates the current file name. The default value is the actual file name.

Publish tags

The following tags can be used anywhere, just as any tag in HTML has the tagname attribute.

• @ Summary description-this label is generally not directly used, because the text before the annotation to the first resolvable label is the @ summary label. That is:/** content */equivalent to/** @ summary content */
• @ Remark summary remarks-this label is generally not directly used, because the text after the label is used in the annotation is @ remark. That is:
  /**
  * @ Return {number}
  * Description
  */
  Equivalent
  /**
  * @ Return {number}
  * @ Remark description
  */
• @ Ignore the annotation.
• @ Define {type} defines the type of the same meaning. For example, @ define {int} {number} can replace number with Int.
• @ Define name: defines comments of the same meaning. You can use define to define the alias of a tag. For example, after @ define description summary, @ description can be used instead of @ summary.
• @ Since [summary] indicates that the specified version is provided.
• @ Deprecated [summary] indicates that a member has been discarded.
• @ See link refers to the link of a file.
• @ Example summary example.
• @ Syntax summary manually specify the syntax.
• @ Name.
• @ Memberof name indicates the parent member.
• @ Type indicates the type.

Type description

• @ Class [name] indicates that this is a class.
• @ Enum [name] indicates that this is enumeration.
• @ Interface [name] indicates that this is an interface.
• @ Member [name] indicates that this is a member.
• @ Property [{type}] [name] indicates that this is an attribute.
• @ Field [{type}] [name] indicates that this is a field.
• @ Method [name] indicates that this is a method.
• @ Event [{type}] [name] indicates the event of the current class.
• @ Getter [{type}] [name] indicates that this is a read-only attribute.
• @ Setter [{type}] [name] indicates that this is a write-only attribute.
• @ Constructor [name] indicates that this is a constructor.
• @ Config {type} [name] indicates that this is a configuration member of the class.

Attribute description

• @ Public indicates public
• @ Private indicates that a class or function is private.
• @ Protected indicates protection.
• @ Internal indicates internal.
• @ Final indicates that a function cannot be overwritten.
• @ Static indicates that a class is static.
• @ Abstract indicates that a class is abstract.
• @ Virtual indicates that a class is abstract.
• @ Const indicates that a value is a constant value.

Others

• @ extends name indicates that one class derives from another class.
• @ implements name indicates that one class derives from another class.
• @ Param {type} Name summary indicates the parameter. If it is an optional parameter with [name], if it is a random parameter with the name of... if there is a default value, use name = value to separate multiple types with any symbol.
• @ return [{type}] [summary] returns.
• {@ link} link.
• {@ code [{type}] >}code.
• @{ represents the character {
• @ indicates the character @
• @}represents characters}
• @ * indicates the character *