jsdoc

转载 2006年06月25日 20:21:00

JSDoc - JavaScript Documentation Tool

Introduction

JSDoc is a tool that parses inline documentation in JavaScript source files, and produces an documentation of the JavaScript code. This is typically in the form of HTML (example), but XML and XMI (UML) export are also supported. JSDoc is based on the (very successful) javadoc tool that was created for the same purpose for the Java programming language.

JSDoc is primarily intended for libraries of object-oriented JavaScript files, although it also works with procedural code. There is a basic ability to determine inheritance built into the parser, although some more obscure dynamic constructs will not be understood (for example, defining a method to set one class as the superclass of another).

Anyone familiar with the javadoc tool will be able to use JSDoc right away; for anyone else it is a very simple matter to get started. JSDoc picks up on comments that are opened with a slash followed by two stars (/**), and closed with the typical star-slash (*/).

Installation

JSDoc is implemented in Perl, as as such, requires the perl executable. This shouldn't be a problem for Linux/Unix users, but Windows users will probably have to install a perl runtime; ActivePerl is recommended.

JSDoc is distributed as a gzipped tarball, and can be downloaded from the JSDoc project page. Once you have downloaded JSDoc-x-x.tgz, just unpack it (tar zxf JSDoc-x-x.tgz on Linux/Unix, use WinZip on Windows), and you're ready to go. You can immediately try out JSDoc on the included test.js JavaScript file by going into the JSDoc directory and entering the command

                  perl jsdoc.pl test.js
               
This should output a set of HTML files in a directory called js_docs_out.

If you get an error message right away that looks something like

                  Can't locate HTML/Template.pm in @INC ......
                
then you will need to install the HTML::Template Perl module. Luckily, this is a very trivial operation thanks to the CPAN. In a Linux/Unix/POSIX-style operating system, open a terminal and run the following command as root:
                  # perl -MCPAN -e 'install HTML::Template'
               

If you're running Windows and ActivePerl, open a command prompt window and enter the following command:

                  C:/> ppm
               
This will start the Perl Package Manager; at the PPM prompt, enter the following two commands (PPM> is the PPM prompt):
                  PPM> install HTML-Template
                  PPM> quit
               

JSDoc should run without problems now.

Usage

The general idea of JSDoc is to pick up the form and documentation of code. A major part of JSDoc's functionality is based around documentation strings embedded in JavaScript code. The definitive reference to writing documentation strings for Java (with a large amount of carry-over to JSDoc) can be found at the javadoc reference page.

 

JSDoc currently supports a subset of javadoc's '@'-prefixed attributes, but the parser is customizable (as explained later). An example JavaScript file (test.js) is included with the JSDoc distribution. Most functionality of JSDoc can be seen within this script file, however for the impatient a small (and incomplete) example of a common usage of JSDoc is shown below

 

                  
                  /**
                   * Shape is an abstract base class. It is defined simply
                   * to have something to inherit from for geometric 
                   * subclasses
                   * @constructor
                   */
                   function Shape(color){
                     this.color = color;
                   }

                   // Bind the Shape_getColor method to the Shape class
                   Shape.prototype.getColor = Shape_getColor;
                    
                   /**
                    * Get the name of the color for this shape
                    * @returns A color string for this shape
                    */
                   function Shape_getColor(){
                     return this.color;
                   }
                    
                   /**
                    * Circle is a subclass of Shape
                    */
                   function Circle(radius){
                     this.radius = radius;
                   }
                    
                   /**
                    * A very rough value for pi
                    */
                   Circle.PI = 3.14;
                   
                   /**
                    * Get the radius of this circle 
                    * @returns The radius of this circle
                    */
                   function Circle_getRadius(){
                     return this.radius;
                   }
                  
                   // Circle is a subclass of Shape
                   Circle.prototype = new Shape(null);
               

 

One important difference between javadoc and JSDoc is that JSDoc deals with a much more dynamic language that javadoc. For example, in JavaScript there are many different ways to make one class a subclass of another. The JSDoc parser is able to catch some of these methods, but for particularly dynamic scripts the parser will not be able to do it all on its own. For that reason, JSDoc is customizable with a file called .jsdoc_config that resides in the JSDoc install directory. In this configuration file, JSDoc's behaviour can be customized for any kind of '@'-prefixed attribute. Although this configuration file actually contains Perl code, simple customizations can be done by someone with minimal experience with Perl.

JSDoc also uses a several non-javadoc '@'-attributes: @constructor and @private are two of the most important ones. As noted above, JavaScript has the capability to be a much more dynamic language than Java. The JSDoc parser can usually find class constructors on it's own, but there are some situations when it needs some additional assistance. For this reason, it is a good practice to always include the @constructor tag in the documentation for a class constructor, as shown below:
                  
                  /**
                   * Nothing is a class that represents nothing
                   * @constructor
                   */
                  function Nothing(){
                     // ... initialization ...
                  }
               
The @private attribute simply displays the marked method as being private.

 

To get more information on the use of the jsdoc.pl executable itself, run it with the --help commandline option.

Tag Reference

The following is a summary of the supported tags ('@'-attributes) that are supported by JSDoc. For actual examples of the usage of these tags, please see the test.js JavaScript file that is included in the JSDoc distribution.
@param Provide information about a function parameter. A datatype indicator can be added between curly braces with this tag, as follows:
        /**
         * @param {String} paramName This is a string parameter
         */
                        
@argument Synonym for @param
@return Provide information about the return value of a function.
@returns Synonym for @return
@author Provide information about the author of a JavaScript file or a function.
@deprecated Signify that a function or class is deprecated, and should not be used if possible.
@see Link to another class or function that is of importance to the current class or function. This tag can take several forms.

To link to another method within the same class:

        @see #methodName
                        

To link to another class:

        @see ClassName
                        

To link to a specific method of another class:

        @see ClassName#methodName
                        
@version Show the version number of the current file or class
@requires Define a dependency upon another class. The syntax for this tag is as follows:
        @requires OtherClassName This is text to be shown
                        
@throws Show that a method can throw a certain type of exception. The syntax for this tag is:
        @throws ExceptionType This is the label text
                        
@exception Synonym for @throws
@link This is a powerful tag that can be used to link to a large number of other pages. It is also the only tag that can be used in the description text of a documentation string before the '@'-tag section. The usage is very similar to that of the @see tag, but the entire tag is wrapped in curly braces. For example:
        /**
         * This utility method is also a member of the {@link String} class, 
         * in the form of the {@link String#utility} method. 
         */
                        
@fileoverview This is a special-use tag. If the first block of documentation in a file starts with a @fileoverview tag, the rest of the documentation block will be used to provide a file overview in the documentation.
@class This tag is used in a constructor's documentation block to provide information about the actual class. The included documentation will then not be included in the constructor's documentation.
@constructor Signify that a function is the constructor for a class.
@type Show the return type of a function. For example:
        /**
         * This function returns a String.
         * @return The name of the current user
         * @type String
         */
                        
@extends Used to show that a class is a subclass of another class. JSDoc is often quite good at picking this up on its own, but in some situations this tag is required.
@private Signify that a function or class is private. Private classes and functions will not be available in the documentation unless JSDoc is run with the --private commandline option.
@final Flag a value as being a final (constant) value.
@member Show that a function is a member of a given class:
        /**
         * @member MyClass
         */
 	function SomeFunc(){
	}
                        
@ignore Tell JSDoc to totally ignore this method.
@base Force JSDoc to view the current class constructor as a subclass of the class given as the value to this tag:
       /**
        * This is a subclass of Shape
        * @constructor
        * @base Shape
        */
       function Circle(){
           // ...
       }
			
@addon Mark a function as being an "addon" to a core JavaScript function that isn't defined within your own sources, as shown below:
	/**
 	 * This is an addon function to SomeCoreClass which is
         * not defined within our own sources. 
	 * @addon
	 */
	SomeCoreClass.someFunction = function(){ 
            // ...
	}		
@exec Experimental!
Force JSDoc to "execute" this method as part of its preprocessing step, in the same way that class contructors are executed. This can allow attributes to be added to a class from within a function.

Frequently Asked Questions

  • I get an error message that says Can't locate HTML/Template.pm in @INC ....... What's going on?

    This means that you don't have the HTML::Template perl module installed. Luckily, it's very easy to remedy this problem; see the Installation section of this page.

  • I've found a bug in JSDoc. What should I do?

    Go to the JSDoc Project Page and register a bug report. You can also send information about the bug to the JSDoc-user mailing list. But just before you do that, please make sure that it's actually a bug that we're talking about, and not just JSDoc acting differently that what you were expecting.

  • JSDoc segfaults! What should I do?

    This is a tough one to answer. JSDoc uses a lot of recursive regular expressions, and sometimes a certain combination of a certain build of perl and a certain JavaScript file will cause perl to segfault while running JSDoc. This problem mostly occurs with binary installations of perl; downloading the most recent source distribution of perl and building it on your own machine seems to solve this problem.

    Another action that can sometimes help in this situation (and doesn't require a new install of perl) is by changing the recursion limit for recursive regexes. You can do this by altering the value given to the constant RECURSION in JSDoc.pm (at line 124 at the time of writing). Changing the value from 10 to a lower value, such as 6, can sometimes take care of this issue. The main risk in taking this action is that some deeply-nested constructs in your JavaScript code might not be processed by JSDoc.

  • I want JSDoc to do X, but it doesn't!

    Well, that's actually not a question, it's more of a statement. However, it is stated quite frequently, so it's not totally out of place here. If you're interested in having a new feature added to JSDoc, you can register a Feature Request at the JSDoc Project Page. You may also want to consider sending information about your request to the JSDoc-user mailing list.

  • Is there a mailing list for JSDoc?

    Okay, I admit that this isn't actually a Frequently Asked Question; it's actually just an attempt to promote the JSDoc-user mailing list.

  • I want to help out with JSDoc. Where should I start?

    First of all, help is very welcome! The most welcome kinds of help are context diffs that fix a bug in JSDoc, but pretty much anything that's an attempt at helping out is appreciated. Use the JSDoc-user mailing list.

More Information

A very complete and informative article (written by Rainer Eschen) on the use of JSDoc can be found at Webetiser. The article is based on JSDoc 1.5, but is still very relevant. I've been told that the article will be updated in the near future.

As noted above, the definitive reference for writing Java docstrings can be found at the javadoc reference page. Please send comments, bugs, complaints, requests for additional information, and whatever else to the JSDoc mailing list.

SourceForge.net Logo

Eslint 规则说明

"no-alert": 0,//禁止使用alert confirm prompt "no-array-constructor": 2,//禁止使用数组构造器 "no-bitwise": 0,//禁止使...
  • helpzp2008
  • helpzp2008
  • 2016年05月26日 15:03
  • 35899

JSDoc 3 入门

原文:http://usejsdoc.org/about-getting-started.html入门JSDoc3是针对JavaScriptAPI文档的生成,类似于JavaDoc或PHPDoc。您可以...
  • liu602182699
  • liu602182699
  • 2015年09月10日 22:12
  • 823

node环境下,jsdoc使用方法简介

一、用express搭建一个node环境。 二、输入npm install jsdoc@" 三、进入.bin目录下,jsdoc -v检查版本信息,同时确定jsdoc是否安装成功。 四、在.bin...
  • Catherian
  • Catherian
  • 2016年12月19日 14:00
  • 1703

JSDoc3的简单使用

官方网站:https://github.com/jsdoc3/jsdoc/ 建议不要直接通过“Download ZIP”功能直接下载,而是到Release中下载稳定版本,比如3.2.2 下载后,直接解...
  • wts
  • wts
  • 2014年02月12日 14:27
  • 2904

谈谈JSDOC对ES6的支持

随着AMD与COMMONJS的深入人心,ES6与babel的组合已成为前端开发必备套件,所以也有必要更新JSDOC的写法,为应用与技术的发展与维护提高更好的文档支持。1. 生成文档的两种选择根据前端代...
  • yiifaa
  • yiifaa
  • 2016年12月07日 12:32
  • 1176

jsdoc利用模板生成js API文档

1.利用npm安装jsdoc模块 npm install jsdoc -g 2.由于jsdoc默认的生成文档模板不好看,所以需要下载一套好看些的模板,如 jaguar.js 下载地址:htt...
  • u013929284
  • u013929284
  • 2017年03月09日 15:42
  • 1315

jsDoc使用方法

JsDoc Toolkit 是一个把js描述格式化成文档的工具。开发者只需按JsDoc的规范写好注释就可以很方便导出文档。它是google 推荐的 JsDoc生成工具。 JsDoc To...
  • sstm888
  • sstm888
  • 2013年05月28日 09:16
  • 924

谈谈JSDOC对ES6的支持

随着AMD与COMMONJS的深入人心,ES6与babel的组合已成为前端开发必备套件,所以也有必要更新JSDOC的写法,为应用与技术的发展与维护提高更好的文档支持。1. 生成文档的两种选择根据前端代...
  • yiifaa
  • yiifaa
  • 2016年12月07日 12:32
  • 1176

配置JSDoc的默认模板

原文:http://usejsdoc.org/about-configuring-default-template.htmlJSDoc的默认模板中提供了几个选项,您可以使用自定义外观和生成的文档内容。...
  • liu602182699
  • liu602182699
  • 2015年09月13日 22:55
  • 1401

利用jsdoc提高自动提示—Webstorm入门指南

很多人第一眼喜欢上idea或Webstorm,是其拥有非常强大的自动提示功能(js中的自动提示准确率和范围远远高过其他编辑器)。 但javascript太灵活了,又是弱类型语言,提示的准确度和详细度...
  • zf900901298
  • zf900901298
  • 2013年11月17日 17:30
  • 2565
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:jsdoc
举报原因:
原因补充:

(最多只允许输入30个字)