JsDoc Toolkit:Javascript文档利器

西风瘦马 发布于 一月 8, 2010

随着Web2.0的风靡，Javascript已经成为一门被人们重新认识的编程语言，由于大量JS开源框架的出现，利用Javascript开发的项目越来越多，越来越大。同时，也有越来越多Javascript开发问题暴露出来，如性能、网页加载速度等，其中，Javascript文档维护也成为了开发者亟待解决的一个难题。

许多现代编程语言都有自己的集成化文档生成工具，像Java有JavaDoc，.NET有NDoc，PHP有PHPDoc，这些自动化文档工具可以根据代码中的注释自动生成代码文档。

JsDoc Toolkit就是这样一个自动化文档工具，它是发布在Google code上的一个开源项目，和其他语言的文档工具一样，它可以自动从Javascript代码中提取注释生成格式化文档。

下载地址

http://code.google.com/p/jsdoc-toolkit/downloads/list

运行环境

JsDoc Toolkit是用Java开发的，运行时需要以下环境：

  1. WindowXP
    java version "1.6.0_03"
    Java(TM) SE Runtime Environment (build 1.6.0_03-b05)

  2. Mac OS X 10.5
    java version "1.5.0_19"
    Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_19-b02-304)

其它版本的Java可能导致JsDoc Toolkit运行失败。

用法

在运行之前，你需要把当前的工作目录切换到JsDoc Toolkit目录，并确保将java.exe所在目录添加到环境变量中。

PLAIN TEXT
HTML:
  1. java -jar jsrun.jar app\run.js -a -t=templates\jsdoc mycode.js

mycode.js是需要生成文档的js代码，如果mycode.js和JsDoc不在同一目录，请加上文件的绝对或者相对路径。如果项目中有多个js，可以使用通配符*来指定多个js文件(*.js)。-e参数指定文档编码，-t参数指定文档模板位置（可以新建或修改模板文件让输出的代码文件更具特色），生成的文档文件在JsDoc目录下的out目录中。为了使用方便，我写了一个批处理文件，你可以将代码保存为run.bat，放到JsDoc目录下：

PLAIN TEXT
HTML:
  1. ::run.bat
  2. @echo off
  3. ::js文件名(换成你的js文件名)
  4. set jsname=jquery.js
  5. ::js文件路径(换成你的js文件路径)
  6. set jspath=C:\test\
  7. echo start...
  8. java -jar jsrun.jar app\run.js -a -e=GBK -t=templates\jsdoc "%jspath%%jsname%.js"
  9. ::out\%jsname%\index.html
  10. echo finished.
  11. pause

常用关键字

author 标识代码作者
class 标识该函数是一个类的构造函数
constant 声明常量
constructor 同class
default 默认值
deprecated 声明已弃用的对象
description 对象描述
event 事件函数
example 例子代码
fileOverview Javascript文件总体描述
ignore 忽略有这个标记的函数
link 与其他JsDoc对象关联
name 显示声明JsDoc不能自动检测的对象
namespace 声明命名空间
param 参数
private 声明私有对象
property 显式声明一个属性
public 声明公开对象
requires 声明所依赖的对象或文件
returns 返回值
see 声明可参考的其它对象
since 声明对象从指定版本开始生效
static 显式声明一个静态对象
throws 声明函数执行过程中可能抛出的异常
type 声明变量类型或者函数返回值类型
version 版本号


详细语法请参阅：JsDoc Toolkit Wiki

以下是官方提示的示例代码：

PLAIN TEXT
JAVASCRIPT:
  1. /**
  2. * @fileoverview This file is to be used for testing the JSDoc parser
  3. * It is not intended to be an example of good JavaScript OO-programming,
  4. * nor is it intended to fulfill any specific purpose apart from
  5. * demonstrating the functionality of the
  6. * <a href='http://sourceforge.net/projects/jsdoc'>JSDoc</a> parser
  7. *
  8. * @author Gabriel Reid gab_reid@users.sourceforge.net
  9. * @version 0.1
  10. */
  11.  
  12.  
  13. /**
  14. * Construct a new Shape object.
  15. * @class This is the basic Shape class.
  16. * It can be considered an abstract class, even though no such thing
  17. * really existing in JavaScript
  18. * @constructor
  19. * @throws MemoryException if there is no more memory
  20. * @throws GeneralShapeException rarely (if ever)
  21. * @return A new shape
  22. */
  23. function Shape(){
  24.  
  25.    /**
  26.     * This is an example of a function that is not given as a property
  27.     * of a prototype, but instead it is assigned within a constructor.
  28.     * For inner functions like this to be picked up by the parser, the
  29.     * function that acts as a constructor <b>must</b> be denoted with
  30.     * the <b>&#64;constructor</b> tag in its comment.
  31.     * @type String
  32.     */
  33.    this.getClassName = function(){
  34.       return "Shape";
  35.    }
  36.  
  37.    /**
  38.     * This is a private method, just used here as an example
  39.     */
  40.    function addReference(){
  41.        // Do nothing...
  42.    }
  43.  
  44. }
  45.  
  46. /**
  47. * Create a new Hexagon instance.
  48. * @extends Shape
  49. * @class Hexagon is a class that is a <i>logical</i> sublcass of
  50. * <a href="Shape.html#">Shape</a> (thanks to the <code>&#64;extends</code> tag), but in
  51. * reality it is completely unrelated to Shape.
  52. * @param {int} sideLength The length of one side for the new Hexagon
  53. */
  54. function Hexagon(sideLength) {
  55. }
  56.  
  57.  
  58. /**
  59. * This is an unattached (static) function that adds two integers together.
  60. * @param {int} One The first number to add
  61. * @param {int http://jsdoc.sourceforge.net/} Two The second number to add
  62. * @author Gabriel Reid
  63. * @deprecated So you shouldn't use it anymore!
  64. */
  65. function Add(One, Two){
  66.     return One + Two;
  67. }
  68.  
  69.  
  70. /**
  71. * The color of this shape
  72. * @type Color
  73. */
  74. Shape.prototype.color = null;
  75.  
  76. /**
  77. * The border of this shape.
  78. * @type int
  79. */
  80. Shape.prototype.border = null;
  81.  
  82. /*
  83. * The assignment of function implementations for Shape, documentation will
  84. * be taken over from the method declaration.
  85. */
  86.  
  87. Shape.prototype.getCoords = Shape_GetCoords;
  88.  
  89. Shape.prototype.getColor = Shape_GetColor;
  90.  
  91. Shape.prototype.setCoords = Shape_SetCoords;
  92.  
  93. Shape.prototype.setColor = Shape_SetColor;
  94.  
  95. /*
  96. * These are all the instance method implementations for Shape
  97. */
  98.  
  99. /**
  100. * Get the coordinates of this shape. It is assumed that we're always talking
  101. * about shapes in a 2D location here.
  102. * @requires Shape The shape class
  103. * @returns A Coordinate object representing the location of this Shape
  104. * @type Coordinate
  105. */
  106. function Shape_GetCoords(){
  107.    return this.coords;
  108. }
  109.  
  110. /**
  111. * Get the color of this shape.
  112. * @see #setColor
  113. * @type Color
  114. */
  115. function Shape_GetColor(){
  116.    return this.color;
  117. }
  118.  
  119. /**
  120. * Set the coordinates for this Shape
  121. * @param {Coordinate} coordinates The coordinates to set for this Shape
  122. */
  123. function Shape_SetCoords(coordinates){
  124.    this.coords = coordinates;
  125. }
  126.  
  127. /**
  128. * Set the color for this Shape
  129. * @param {Color} color The color to set for this Shape
  130. * @param other There is no other param, but it can still be documented if
  131. *              optional parameters are used
  132. * @throws NonExistantColorException (no, not really!)
  133. * @see #setColor
  134. */
  135. function Shape_SetColor(color){
  136.    this.color = color;
  137. }
  138.  
  139. /**
  140. * Clone this shape
  141. * @returns A copy of this shape
  142. * @type Shape
  143. * @author Gabriel Reid
  144. */
  145. Shape.prototype.clone = function(){
  146.    return new Shape();
  147. }
  148.  
  149. /**
  150. * Create a new Rectangle instance.
  151. * @class A basic rectangle class, inherits from Shape.
  152. * This class could be considered a concrete implementation class
  153. * @constructor
  154. * @param {int} width The optional width for this Rectangle
  155. * @param {int} height Thie optional height for this Rectangle
  156. * @author Gabriel Reid
  157. * @see Shape Shape is the base class for this
  158. */
  159. function Rectangle(width, // This is the width
  160.                   height // This is the height
  161.                   ){
  162.    if (width){
  163.       this.width = width;
  164.       if (height){
  165.      this.height = height;
  166.       }
  167.    }
  168. }
  169.  
  170.  
  171. /* Inherit from Shape */
  172. Rectangle.prototype = new Shape();
  173.  
  174. /**
  175. * Value to represent the width of the Rectangle.
  176. * <br>Text in <b>bold</b> and <i>italic</i> and a
  177. * link to <a href="http://sf.net">SourceForge</a>
  178. * @private
  179. * @type int
  180. */
  181. Rectangle.prototype.width = 0;
  182.  
  183. /**
  184. * Value to represent the height of the Rectangle
  185. * @private
  186. * @type int
  187. */
  188. Rectangle.prototype.height = 0;
  189.  
  190. /**
  191. * Get the type of this object.
  192. * @type String
  193. */
  194. Rectangle.prototype.getClassName= function(){
  195.     return "Rectangle";
  196. }
  197.  
  198. /*
  199. * These are all the instance method implementations for Rectangle
  200. */
  201.  
  202. Rectangle.prototype.getWidth = Rectangle_GetWidth;
  203.  
  204. Rectangle.prototype.getHeight = Rectangle_GetHeight;
  205.  
  206. Rectangle.prototype.setWidth = Rectangle_SetWidth;
  207.  
  208. Rectangle.prototype.setHeight = Rectangle_SetHeight;
  209.  
  210. Rectangle.prototype.getArea = Rectangle_GetArea;
  211.  
  212.  
  213. /**
  214. * Get the value of the width for the Rectangle
  215. * @type int
  216. * @see #setWidth
  217. */
  218. function Rectangle_GetWidth(){
  219.    return this.width;
  220. }
  221.  
  222. /**
  223. * Get the value of the height for the Rectangle.
  224. * Another getter is the <a href="Shape.html#getColor">Shape.getColor()</a> method in the
  225. * <a href="Shape.html#">base Shape class</a>.
  226. * @return The height of this Rectangle
  227. * @type int
  228. * @see #setHeight
  229. */
  230. function Rectangle_GetHeight(){
  231.     return this.height;
  232. }
  233.  
  234. /**
  235. * Set the width value for this Rectangle.
  236. * @param {int} width The width value to be set
  237. * @see #setWidth
  238. */
  239. function Rectangle_SetWidth(width){
  240.    this.width = width;
  241. }
  242.  
  243. /**
  244. * Set the height value for this Rectangle.
  245. * @param {int} height The height value to be set
  246. * @see #getHeight
  247. */
  248. function Rectangle_SetHeight(height){
  249.    this.height = height;
  250. }
  251.  
  252. /**
  253. * Get the value for the total area of this Rectangle
  254. * @return total area of this Rectangle
  255. * @type int
  256. */
  257. function Rectangle_GetArea(){
  258.    return width * height;
  259. }
  260.  
  261.  
  262. /**
  263. * Create a new Square instance.
  264. * @class A Square is a subclass of <a href="Rectangle.html#">Rectangle</a>
  265. * @param {int} width The optional width for this Rectangle
  266. * @param {int} height The optional height for this Rectangle
  267. */
  268. function Square(width, height){
  269.    if (width){
  270.       this.width = width;
  271.       if (height){
  272.      this.height = height;
  273.       }
  274.    }
  275.  
  276. }
  277.  
  278. /* Square is a subclass of Rectangle */
  279. Square.prototype = new Rectangle();
  280.  
  281.  
  282. /*
  283. * The assignment of function implementation for Shape.
  284. */
  285. Square.prototype.setWidth = Square_SetWidth;
  286.  
  287. Square.prototype.setHeight = Square_SetHeight;
  288.  
  289.  
  290.  
  291. /**
  292. * Set the width value for this Square.
  293. * @param {int} width The width value to be set
  294. * @see #getWidth
  295. */
  296. function Square_SetWidth(width){
  297.    this.width = this.height = width;
  298. }
  299.  
  300. /**
  301. * Set the height value for this Square
  302. * Sets the <a href="Rectangle.html#height">height</a> attribute in the Rectangle.
  303. * @param {int} height The height value to be set
  304. */
  305. function Square_SetHeight(height){
  306.    this.height = this.width = height;
  307. }
  308.  
  309.  
  310. /**
  311. * Create a new Circle instance based on a radius.
  312. * @class Circle class is another subclass of Shape
  313. * @param {int} radius The optional radius of this Circle
  314. */
  315. function Circle(radius){
  316.    if (radius){
  317.       this.radius = radius;
  318.    }
  319. }
  320.  
  321. /* Circle inherits from Shape */
  322. Circle.prototype = new Shape();
  323.  
  324. /**
  325. * The radius value for this Circle
  326. * @private
  327. * @type int
  328. */
  329. Circle.prototype.radius = 0;
  330.  
  331. /**
  332. * A very simple class (static) field that is also a constant
  333. * @final
  334. * @type float
  335. */
  336. Circle.PI = 3.14;
  337.  
  338. Circle.createCircle = Circle_CreateCircle;
  339.  
  340. Circle.prototype.getRadius = Circle_GetRadius;
  341.  
  342. Circle.prototype.setRadius = Circle_SetRadius;
  343.  
  344. /**
  345. * Get the radius value for this Circle
  346. * @type int
  347. * @see #setRadius
  348. */
  349. function Circle_GetRadius(){
  350.    return this.radius;
  351. }
  352.  
  353. /**
  354. * Set the radius value for this Circle
  355. * @param {int} radius The radius value to set
  356. * @see #getRadius
  357. */
  358. function Circle_SetRadius(radius){
  359.    this.radius = radius;
  360. }
  361.  
  362. /**
  363. * An example of a  class (static) method that acts as a factory for Circle
  364. * objects. Given a radius value, this method creates a new Circle.
  365. * @param {int} radius The radius value to use for the new Circle.
  366. * @type Circle
  367. */
  368. function Circle_CreateCircle(radius){
  369.     return new Circle(radius);
  370. }
  371.  
  372.  
  373. /**
  374. * Create a new Coordinate instance based on x and y grid data.
  375. * @class Coordinate is a class that can encapsulate location information.
  376. * @param {int} x The optional x portion of the Coordinate
  377. * @param {int} y The optinal y portion of the Coordinate
  378. */
  379. function Coordinate(x, y){
  380.    if (x){
  381.       this.x = x;
  382.       if (y){
  383.      this.y = y;
  384.       }
  385.    }
  386. }
  387.  
  388. /**
  389. * The x portion of the Coordinate
  390. * @type int
  391. * @see #getX
  392. * @see #setX
  393. */
  394. Coordinate.prototype.x = 0;
  395.  
  396. /**
  397. * The y portion of the Coordinate
  398. * @type int
  399. * @see #getY
  400. * @see #setY
  401. */
  402. Coordinate.prototype.y = 0;
  403.  
  404. Coordinate.prototype.getX = Coordinate_GetX;
  405. Coordinate.prototype.getY = Coordinate_GetY;
  406. Coordinate.prototype.setX = Coordinate_SetX;
  407. Coordinate.prototype.setY = Coordinate_SetY;
  408.  
  409. /**
  410. * Gets the x portion of the Coordinate.
  411. * @type int
  412. * @see #setX
  413. */
  414. function Coordinate_GetX(){
  415.    return this.x;
  416. }
  417.  
  418. /**
  419. * Get the y portion of the Coordinate.
  420. * @type int
  421. * @see #setY
  422. */
  423. function Coordinate_GetY(){
  424.    return this.y;
  425. }
  426.  
  427. /**
  428. * Sets the x portion of the Coordinate.
  429. * @param {int} x The x value to set
  430. * @see #getX
  431. */
  432. function Coordinate_SetX(x){
  433.    this.x = x;
  434. }
  435.  
  436. /**
  437. * Sets the y portion of the Coordinate.
  438. * @param {int} y The y value to set
  439. * @see #getY
  440. */
  441. function Coordinate_SetY(y){
  442.    this.y = y;
  443. }
  444.  
  445. /**
  446. * @class This class exists to demonstrate the assignment of a class prototype
  447. * as an anonymous block.
  448. */
  449. function ShapeFactory(){
  450. }
  451.  
  452. ShapeFactory.prototype = {
  453.    /**
  454.     * Creates a new <a href="Shape.html#">Shape</a> instance.
  455.     * @return A new <a href="Shape.html#">Shape</a>
  456.     * @type Shape
  457.     */
  458.    createShape: function(){
  459.       return new Shape();
  460.    }
  461. }
  462.  
  463. /**
  464. * An example of a singleton class
  465. */
  466. MySingletonShapeFactory = new function(){
  467.  
  468.    /**
  469.     * Get the next <a href="Shape.html#">Shape</a>
  470.     * @type Shape
  471.     * @return A new <a href="Shape.html#">Shape</a>
  472.     */
  473.    this.getShape = function(){
  474.       return null;
  475.    }
  476.  
  477. }
  478.  
  479.  
  480. /**
  481. * Create a new Foo instance.
  482. * @class This is the Foo class. It exists to demonstrate 'nested' classes.
  483. * @constructor
  484. * @see Foo.Bar
  485. */
  486. function Foo(){}
  487.  
  488. /**
  489. * Creates a new instance of Bar.
  490. * @class This class exists to demonstrate 'nested' classes.
  491. * @constructor
  492. * @see Foo.Bar
  493. */
  494. function Bar(){}
  495.  
  496. /**
  497. * Nested class
  498. * @constructor
  499. */
  500. Foo.Bar = function(){this.x = 2;}
  501.  
  502. Foo.Bar.prototype = new Bar();
  503.  
  504. Foo.Bar.prototype.y = '3';

文章来源：西风瘦马博客http://blog.tugai.net/

4 评论

  1. George Wing 发布于 十一月 18th, 2010

    学习了~

  2. Ester Barginear 发布于 七月 29th, 2011

    With almost everything that appears to be building throughout this area, many of your viewpoints tend to be somewhat radical. Even so, I appologize, but I do not subscribe to your entire strategy, all be it exciting none the less. It appears to everybody that your opinions are actually not entirely validated and in reality you are generally your self not even completely certain of your argument. In any case I did take pleasure in examining it.

  3. 环保锡条 发布于 八月 1st, 2011

    Currently it sounds like Movable Type is the best blogging platform out there right now. (from what I’ve read) Is that what you’re using on your blog?

  4. cloud computing nyc 发布于 十月 12th, 2011

    One of my favorite posts.

发布评论