Jsdocx Annotation Specification

Contents

• 1. Introduction
• 2. The Comment Style
• 3. The Annotation Tags
• 3.1 Overview
• 3.2 Tags List
• 4. Generation with 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 to use the functional style API, this is not a good thing. Jsdocx require the full object-oriented style of library design: that everything is class. At this stage, Jsdocx has no plans to support the comments of the functions, you may consider the following measures before using jsdocx:
1) redesign object-oriented style API
2) comment functions with a virtual class


In addition, Jsdocx scanned 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]}*

Jsdocx Annotation Attributes：

tagName:         the tag name of the annotation
markTarget:      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

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

@copyright

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

@license

markTarget: File
isMultiLine: N
syntax: @license <licenseName> 
sample: @license LGPLv3

@requires

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

@version

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

@author

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

@date

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

@since

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

@struct

markTarget: Class
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}
     }
}

@see

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

@deprecated

markTarget: 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

markTarget: 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

markTarget: 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

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

@protected

markTarget: 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

markTarget: 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 

@native

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

@class

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

@extends

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

@mix

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

@abstract

markTarget: 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

markTarget: 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

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

@method

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

@param

markTarget: 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

markTarget: 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

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

@override

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

@field

markTarget: 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

markTarget: 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

4. Generation with 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>

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

4.2 Using in java

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

5. Sanguo Example

The Sanguo Example is a JavaScript game demo in jsdocx, which comments with Jsdocx Annotations. You can see the online document: sanguo.

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


---


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