[关闭]
@EncyKe 2016-10-26T02:43:01.000000Z 字数 3340 阅读 1571

手册:JSDoc

#手册



1. 命名空间

  1. /**
  2. * @namespace
  3. */
  4. var IFR = {};

2. 函数

  1. /**
  2. * @description 求两个数的和
  3. * 1) 参数将强制转换为Number类型
  4. * 2) 这是一个全局的公用方法
  5. * @method add
  6. * @param {Number} num1 数1
  7. * @param {Number} num2 数2
  8. * @return {Number} 数1和数2的和
  9. *
  10. * @since 2016-05-16
  11. * @author xxx
  12. * @example
  13. * var sum = add(3,5);
  14. * alert(sum);
  15. * // ==> 8
  16. * @static
  17. */
  18. function add (num1,num2) {
  19. return Number(num1) + Number(num2);
  20. }
  21. /**
  22. * doSomething is a function
  23. * @param {String} str a string parameter
  24. * @param {Number} num a number parameter
  25. * @return {{name: String, age: Number}}
  26. */
  27. var doSomething = function(str, num){
  28. return {name : str, age : num + 1};
  29. };

3. 类和构造器

  1. /**
  2. * @class 类描述
  3. * @extends cc.Class
  4. */
  1. /**
  2. * @constructor
  3. */
  4. var Employee = function(){
  5. /** @type String */
  6. this.name = "";
  7. /** @type Number */
  8. this.age = 1;
  9. };
  10. var emp = new Employee();
  11. emp.name = "Terry";
  12. emp.age = 18;

4. 字面量对象

  1. /**
  2. * Manager virtual Type
  3. * @typedef {Object} Manager
  4. * @property {String} name
  5. * @property {Number} age
  6. * @property {Array.<Employee>} employees
  7. * @type Manager
  8. */
  9. var manager = {
  10. name : "Terry",
  11. age : 28,
  12. employees : [
  13. {
  14. name : "Losyn",
  15. age : 18
  16. },
  17. {
  18. name : "Bruce",
  19. age : 18
  20. }
  21. ]
  22. };
  1. /**
  2. *
  3. * @param {function(this:HTMLTableElement, Number)} f
  4. * @param {String} otherData
  5. */
  6. var doSomething5 = function(f, otherData){};

5. 参数

5.1. 任意个 Number 类型的参数

  1. /**
  2. *
  3. * @param {...Number} args
  4. */
  5. var doSomething8 = function (args) {};

5.2. 指明某一个参数是可选的

  1. /**
  2. *
  3. * @param {Number} age
  4. * @param {String=} name
  5. */
  6. var doSomething9 = function (age, name) {};

5.3. 任意类型 {*}

5.4. 不确定类型 {?}

5.5. 可为 null 的类型

5.6. 不可为 null 的类型

5.7. 函数类型

5.8. 类型名

5.9. 集合类型

5.10. 联合类型

6. 示例

  1. /**
  2. * A shape.
  3. * @interface
  4. */
  5. function Shape() {}
  6. Shape.prototype.draw = function () {};
  7. /**
  8. * A polygon.
  9. * @interface
  10. * @extends {Shape}
  11. */
  12. function Polygon() {}
  13. Polygon.prototype.getSides = function () {};
  14. /**
  15. * Person类
  16. * @class
  17. * @extends {Class}
  18. */
  19. var Person = Class.extend(
  20. /** @lends Person.prototype */
  21. {
  22. /**
  23. * 构造函数
  24. * @constructs
  25. * @param car {Car}
  26. */
  27. init: function (car) {
  28. /** @type {Car} */
  29. this.car = car;
  30. },
  31. /**
  32. * 能否驾驶
  33. *
  34. * @return {Boolean}
  35. */
  36. canDrive: function () {
  37. return this.car.size > 10;
  38. }
  39. }
  40. );
  41. /** @namespace */
  42. var Tools = {};
  43. /**
  44. * @memberof Tools
  45. * @param {String} str
  46. * @private
  47. **/
  48. var hammer = function(str) {
  49. };
  50. Tools.hammer = hammer;

7. 速查表

@abstract
抽象,必须由继承者实现(或者覆盖);
@access
访问级别(private、public或者protected);
@alias
别名;
@augments
参数;
@author
作者;
@borrows
借用;
@callback
回调函数;
@classdesc
类描述;
@constant
常量;
@constructor
明确一个函数是某个类的构造函数,可以使用new创建一个实例;
@constructs
构造;
@copyright
版权;
@default
默认值;
@deprecated
指示一个函数已经废弃,不建议使用,而且在将来版本的代码中可能会彻底删除,要避免使用这段代码;
@desc
描述;
@enum
枚举值;
@event
事件;
@example
范例;
@exports
模块导出(模块化);
@external
外部模块(模块化);
@file
文件;
@fires
可触发的事件;
@global
全局对象;
@ignore
JSDoc 会忽略有这个标记的函数;
@inner
内联对象;
@instance
实例;
@kind
标识类型;
@lends
遍历属于同一个标识的所有属性;
@license
软件授权;
@link
内联;
@member
成员;
@memberof
属于某成员;
@method
方法;
@mixes
合并;
@mixin
最小化;
@module
模块(模块化);
@name
名称;
@namespace
命名空间;
@param
参数;
@private
私有的(访问控制);
@property
属性;
@protected
受保护的(访问控制);
@public
公开的(访问控制);
@readonly
只读的;
@requires
依赖(模块化);
@return
返回值;
@see
引用;
@since
开始于;
@static
静态的;
@summary
概述;
@this
解释this关键字;
@throws
可能抛出的异常;
@todo
待办事项;
@tutorial
引用指导手册;
@type
类型;
@typedef
自定义类型;
@variation
区分不同的对象具有相同名称的;
@version
版本;
{@link ...}, {@linkplain ...}, {@linkcode ...}, {@tutorial ...}
内联标签;

附:参考

添加新批注
在作者公开此批注前,只有你和作者可见。
回复批注