Jsdocx Annotation Specification

History

• 1.1.0_20111219

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> 
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 event schema see: http://json-schema.org/ 

sample: 
@event moved
{
     "description": "fires after a sprite movement"
     ,"type":"arguments"
     ,"properties":{
        "this":{"type":"sanguo.d2.Sprite","required":true}
        ,"x":{"type":"int","required":true}
        ,"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: Void,Object,Array,Number,Int,Float,String,Date,Boolean,Error,Function,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>
• Mark a field of the class, allows many types
• Native types are: Object,Array,Number,Int,Float,String,Date,Boolean,Error,Function,HTMLElement  
sample: @field {Int|String} code

@constant

---

target: Field
isMultiLine: N
syntax: @field <type{"|"type}> <fieldName>
• Mark a final static field of the class, allows many types
• Native types are: Object,Array,Number,Int,Float,String,Date,Boolean,Error,Function,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 will scan any one of these to generate the document.

Rule 2: Jsdocx will scan all of "@author" to generate the document.

Rule 3: Jsdocx will scan the lastest value of "@version" and "@date" to generate the document.

Rule 4: The struct classes will not found in the "all classes" directory, but found in linking with other classes.

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
-Souredir=<directoryPath>: the javascript source's directory
-Docdir=<directoryPath>: the generating html document's directory
-Clean: clean the html document's directory before generating

Note:
if you don't set up the argument "Docdir", then the generating document's directory named "jsdocx" 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 JavaScript game demo named "sanguo", which comments with the Jsdocx annotations.
You can see the online document: sanguo.

Download "org.dragonfly.jsdocx-<version>.jar", and execute this command:
java -cp org.dragonfly.jsdocx-<version>.jar org.dragonfly.jsdocx.example.SanguoExample

In the directory, You will find the following new path generated: org/dragonfly/jsdocx/example/sanguo/js/jsdocx

The "index.html" under the path, open it with browser.


---


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