Jsdocx Annotation Specification

History

• 1.1.0_20111219
• 1.1.0_20111226

Contents

• 1. Introduction
• 2. The Comment Style
• 3. The Annotation Tags
• 3.1 Overview
• 3.2 Tags List
• 3.3 Generating Rules
• 4. Using with a jar
• 4.1 Using command line
• 4.2 Using in java
• 5. Sanguo Example

1. Introduction

Jsdocx is a java tool for scanning Js code and generating API documentation automatically.
Jsdocx defines a standard set of annotations specification. This document describes all details of the specification.

Many JavaScript libraries's API has used functional style, this is not a good thing for advanced development. Jsdocx requires full object-oriented style API design: everything is class. Now, Jsdocx do not directly support the feature which comments on a function, you may consider the following measures before using jsdocx:
1) redesign object-oriented style API
2) comment functions with a virtual class


Note:
Jsdocx scans the source code sequentially, requires all members comments of a class is continuous, otherwise it will identify the wrong class members.

2. The Comment Style

Jsdocx support JavaScript's multi-line comment style. Jsdocx annotation start with "@", similar to Javadoc:

/**
 * @{tagName} {comment}
 */

Also directly write description on the annotation of a class or member:

/**
 * {Description}
 * @class MyClass
 */
MyClass = function(){}  

3. The Annotation Tags

3.1 Overview

Jsdocx Annotation's format is: The "@tagName" at the beginning, followed by zero or more whitespace-separated text fragments.

@tagName{whitespace<text fragments>}

Annotation's Attributes：
tagName:         the tag name of the annotation
target:      the mark target is：File, Class, Method or Field
isMultiLine:     single line or multi line
syntax:          describe the syntax format with BNF

3.2 Tags List

@project

---

target: File
isMultiLine: Y
syntax: @project <projectName> [description]
sample: @project JSDK JavaScript Development Kit

@copyright

---

target: File
isMultiLine: N
syntax: @copyright <copyrightText>
sample: @copyright Copyright (c) 2004-2011, Dragonfly.org. All rights reserved.

@license

---

target: File
isMultiLine: N
syntax: @license <licenseName> [description]
sample: @license LGPLv3

@requires(To be supported)

---

target: File
isMultiLine: N
syntax: @requires <resourcePath> 
sample: 
@requires /library/blackbirdjs-1.0/blackbird.js
@requires /library/blackbirdjs-1.0/blackbird.css

@version

---

target: File
isMultiLine: N
syntax: @version <versionNumber> 
sample: @version 1.0.0

@author

---

target: File
isMultiLine: N
syntax: @author <authorName> 
sample: @author Feng.chun

@date

---

target: File
isMultiLine: N
syntax: @date <codingDate>
• The format is: yyyy-mm-dd 
sample: @date 1977-04-15

@since(To be supported)

---

target: File
isMultiLine: N
syntax: @since <versionNumber> 
sample: @since 1.0.0

@see(To be supported)

---

target: Class, Method, Field
isMultiLine: N
syntax: @see <className{#memberName}> 
sample: @see js.Lang#random

@deprecated

---

target: Class, Method, Field
isMultiLine: Y
syntax: @deprecated [version] [reason] 
• If a class is deprecated, then its every method or field is deprecated.
sample: @deprecated 1.2 i don't like

@final

---

target: Class, Method, Field
isMultiLine: N
syntax: @final 
• Mark a final class or method or field
• If a class is final, then its every method or field is final
sample: @final 

@static

---

target: Class, Method, Field
isMultiLine: N
syntax: @static 
• Mark a static class or method or field
• If a class is static, then its every method or field is static
sample: @static 

@public

---

target: Class, Method, Field
isMultiLine: N
syntax: @public 
• The default is public when not marked
sample: @public 

@protected

---

target: Class, Method, Field
isMultiLine: N
syntax: @protected 
• A protected class be only called by same package or same file
• A protected field or method be only called by class self or subclasses 
sample: @protected 

@private

---

target: Class, Method, Field
isMultiLine: N
syntax: @private 
• A private class be only called by same file 
• A private field or method be only called by class self 
sample: @private 

@struct

---

target: File, Class, Method, Field
isMultiLine: Y
syntax: @struct <structName> <structSchema>  
• Mark a json struct class without source code
• The struct schema see: http://json-schema.org/ 

sample: 
@struct sanguo.Knight$Config {
     "description": "the arguments of sanguo.Knight"
     ,"type":"object"
     ,"properties":{
         "side":{"type":"string","required":true}
         ,"level":{"type":"string","required":false}
     }
}

@native

---

target: Class
isMultiLine: N
syntax: @native <nativeObjectName>
• Mark a javascript native object 
sample: @native String

@class

---

target: Class
isMultiLine: N
syntax: @class <className>
sample: @class sanguo.Engine

@extends

---

target: Class
isMultiLine: N
syntax: @extends <className>
sample: @extends sanguo.d2.Sprite

@mix

---

target: Class
isMultiLine: N
syntax: @mix <otherClassName>
• Mix otherClassName's prototype into the class
sample: @mix sanguo.MoveProvider

@abstract

---

target: Class, Method
isMultiLine: N
syntax: @abstract 
• An abstract class has a abstract method at least
• An abstract method is a empty method
sample: @abstract 

@event

---

target: Class
isMultiLine: Y
syntax: @event <eventName> [eventSchema]
• The json schema see: http://json-schema.org/ 
• For describle event, we use the custom type value: "function" and some custom properties: "scope", "arguments"  

sample: 
@event moving 
{
     "description": "fires before a sprite movement"
     ,"type":"function"
     ,"scope":{"type":"sanguo.d2.Sprite","required":true}
     ,"arguments":{
         "type":"array"
         ,"items":[
             {"id":"x","type":"int","required":true}
             {"id":"y","type":"int","required":true}
         ]
     }
}

@constructor

---

target: Method
isMultiLine: N
syntax: @constructor 
• Mark the class's constructor function 
sample: @constructor

@method

---

target: Method
isMultiLine: N
syntax: @method <methodName> 
sample: @method

@param

---

target: Method
isMultiLine: N
syntax: @param <type{"|"type}> <paramName[:optional]> [description] 
• Mark a parameter of the method, allows many types
• Native types are: Object,Array,Number,Int,Float,String,Date,Boolean,Error,Function,HTMLElement  
sample: 
@param {String} name the name of Yomi 
@param {Date|String} birthday:optional the birthday of Yomi 

@return

---

target: Method
isMultiLine: N
syntax: @return <type{"|"type}> [description] 
• Native types are: Object,Array,Number,Int,Float,String,Date,Boolean,Error,Function,Event,HTMLElement  
sample: @return {Date|String} the birthday of Yomi 

@throws

---

target: Method
isMultiLine: N
syntax: @throws <errorType> [description]  
sample: 
@throws {TypeError} when the arguments invalid 
@throws {ReadError} when the reading failure 

@override(To be supported)

---

target: Method
isMultiLine: N
syntax: @override 
• Mark the method override a superclass's same name method 
sample: @override 

@field

---

target: Field
isMultiLine: N
syntax: @field <type{"|"type}> <fieldName> [description]
• Mark a field of the class, allows many types
• Native types are: Object,Array,Number,Int,Float,String,Date,Boolean,Error,Function,Event,HTMLElement  
sample: @field {Int|String} code

@constant

---

target: Field
isMultiLine: N
syntax: @field <type{"|"type}> <fieldName> [description]
• Mark a final static field of the class, allows many types
• Native types are: Object,Array,Number,Int,Float,String,Date,Boolean,Error,Function,Event,HTMLElement  
sample: @constant {String} JSDOCX_VERSION

3.3 Generating Rules

Rule 1: Some tags(like: @project, @copyright, @license) can be defined in any JS file, Jsdocx scans any one of these for generating the document.

Rule 2: Jsdocx scans and lists all of "@author".

Rule 3: Jsdocx scans the biggest "@version" and the latest "@date" for generating the document.

Rule 4: Jsdocx generates three types class-documents for three different classes:
native class(@native), struct class(@struct), custom class(@class).

Rule 5: The struct classes not be listed under the "all classes" of the HTML page.

Rule 6: Jsdocx scans the only tag "@return" for "@method".

Rule 7: When you define a field with @field or @constant like this:

/**
 * description2
 * @field {type} fieldName description1
*/

The description of this field is: description1+description2

Rule 8: When generate html pages, Jsdocx don't escape the HTML special chars in all descriptions.

Rule 9: When a class is marked with @static, then all members of the class be identified as static automatically.

Rule 10: The following two marking ways are equivalent:

marking way1:

/**
 * @constant {type} fieldName
*/

marking way2:

/**
 * @field {type} fieldName
 * @static
 * @final
 */

4. Using with a jar

Download the lastest jar into your disk: org.dragonfly.jsdocx-<version>.jar

4.1 Using command line

java -cp org.dragonfly.jsdocx-<version>.jar org.dragonfly.jsdocx.JsdocCreator -Souredir=<js source's directory> -Docdir=<js document's directory>


Arguments:
-Charset=<charset>: the generating html document's charset. The default value is "UTF-8".
-Souredir=<directoryPath>: the javascript source's directory.
-Docdir=<directoryPath>: the generating html document's directory.
-Clean=<true|false>: If true then clean the html document's directory before generating.

Note:
if you don't set up the argument "Docdir", then the generated document's directory named "jsdocx" will be under the "Souredir".

4.2 Using in java

JsdocConfig config = new JsdocConfig();
config.setSourceDir("the javascript source's directory");
new JsdocCreator(config).generate();

5. Sanguo Example

Jsdocx has a demo named "sanguo", which comments with Jsdocx standard annotations.
You can see the online document: sanguo.

Or download "org.dragonfly.jsdocx-<version>.jar" to <your-dir> , and execute this command:
java -cp org.dragonfly.jsdocx-<version>.jar org.dragonfly.jsdocx.example.SanguoExample

Under the directory: <your-dir>/org/dragonfly/jsdocx/example/sanguo/js/jsdocx/ , You can open "index.html" with your browser.


---


Copyright© 2004-2012, Dragonfly.org. All rights reserved.
https://sourceforge.net/projects/jsdocx