├── .gitignore ├── php ├── param │ ├── docs │ │ └── demo.png │ ├── index.php │ └── README.md ├── var │ ├── docs │ │ ├── demo1.png │ │ └── demo2.png │ ├── index.php │ └── README.md ├── internal │ ├── docs │ │ └── demo.jpg │ ├── outer.php │ ├── README.md │ └── index.php ├── method │ ├── docs │ │ ├── demo1.jpg │ │ └── demo2.jpg │ ├── README.md │ └── index.php ├── return │ ├── docs │ │ └── demo.png │ ├── README.md │ └── index.php ├── throws │ ├── docs │ │ └── demo.png │ ├── README.md │ └── index.php ├── deprecated │ ├── docs │ │ └── demo.jpg │ ├── README.md │ └── index.php ├── property │ ├── docs │ │ ├── demo1.png │ │ └── demo2.png │ ├── index.php │ └── README.md ├── inheritdoc │ ├── docs │ │ ├── demo1.jpg │ │ └── demo2.jpg │ ├── README.md │ └── index.php ├── author │ ├── index.php │ └── README.md ├── link │ ├── index.php │ └── README.md ├── see │ ├── README.md │ └── index.php └── README.md ├── javascript ├── member │ ├── docs │ │ └── demo.png │ ├── demo.js │ └── README.md ├── param │ ├── docs │ │ ├── demo1.png │ │ └── demo2.png │ ├── demo3.js │ ├── demo2.js │ ├── demo1.js │ └── README.md ├── see │ ├── docs │ │ └── demo1.gif │ ├── demo.js │ └── README.md ├── type │ ├── docs │ │ ├── demo1.png │ │ ├── demo2.png │ │ └── demo3.png │ ├── demo2.js │ ├── demo1.js │ └── README.md ├── abstract │ ├── docs │ │ └── demo.png │ ├── README.md │ └── demo.js ├── returns │ ├── docs │ │ ├── demo1.png │ │ └── demo2.png │ ├── demo.js │ └── README.md ├── constructor ├── deprecated │ ├── docs │ │ ├── demo1.png │ │ └── demo2.png │ ├── demo1.js │ ├── demo2.js │ └── README.md ├── inheritdoc │ ├── docs │ │ └── demo.png │ ├── README.md │ └── demo.js ├── default │ ├── README.md │ └── demo.js ├── throws │ ├── index.js │ └── README.md ├── this │ └── index.js ├── access │ └── index.js └── README.md ├── LICENSE └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | \.idea 2 | vendor 3 | composer\.lock 4 | *\.out 5 | *\.swp 6 | test.php 7 | bin 8 | runtime/* -------------------------------------------------------------------------------- /php/param/docs/demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/param/docs/demo.png -------------------------------------------------------------------------------- /php/var/docs/demo1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/var/docs/demo1.png -------------------------------------------------------------------------------- /php/var/docs/demo2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/var/docs/demo2.png -------------------------------------------------------------------------------- /php/internal/docs/demo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/internal/docs/demo.jpg -------------------------------------------------------------------------------- /php/method/docs/demo1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/method/docs/demo1.jpg -------------------------------------------------------------------------------- /php/method/docs/demo2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/method/docs/demo2.jpg -------------------------------------------------------------------------------- /php/return/docs/demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/return/docs/demo.png -------------------------------------------------------------------------------- /php/throws/docs/demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/throws/docs/demo.png -------------------------------------------------------------------------------- /php/deprecated/docs/demo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/deprecated/docs/demo.jpg -------------------------------------------------------------------------------- /php/property/docs/demo1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/property/docs/demo1.png -------------------------------------------------------------------------------- /php/property/docs/demo2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/property/docs/demo2.png -------------------------------------------------------------------------------- /javascript/member/docs/demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/member/docs/demo.png -------------------------------------------------------------------------------- /javascript/param/docs/demo1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/param/docs/demo1.png -------------------------------------------------------------------------------- /javascript/param/docs/demo2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/param/docs/demo2.png -------------------------------------------------------------------------------- /javascript/see/docs/demo1.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/see/docs/demo1.gif -------------------------------------------------------------------------------- /javascript/type/docs/demo1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/type/docs/demo1.png -------------------------------------------------------------------------------- /javascript/type/docs/demo2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/type/docs/demo2.png -------------------------------------------------------------------------------- /javascript/type/docs/demo3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/type/docs/demo3.png -------------------------------------------------------------------------------- /php/inheritdoc/docs/demo1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/inheritdoc/docs/demo1.jpg -------------------------------------------------------------------------------- /php/inheritdoc/docs/demo2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/php/inheritdoc/docs/demo2.jpg -------------------------------------------------------------------------------- /javascript/abstract/docs/demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/abstract/docs/demo.png -------------------------------------------------------------------------------- /javascript/returns/docs/demo1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/returns/docs/demo1.png -------------------------------------------------------------------------------- /javascript/returns/docs/demo2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/returns/docs/demo2.png -------------------------------------------------------------------------------- /javascript/constructor/docs/demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/constructor/docs/demo.png -------------------------------------------------------------------------------- /javascript/deprecated/docs/demo1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/deprecated/docs/demo1.png -------------------------------------------------------------------------------- /javascript/deprecated/docs/demo2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/deprecated/docs/demo2.png -------------------------------------------------------------------------------- /javascript/inheritdoc/docs/demo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yinggaozhen/doc-demo/HEAD/javascript/inheritdoc/docs/demo.png -------------------------------------------------------------------------------- /javascript/default/README.md: -------------------------------------------------------------------------------- 1 | # @default 2 | 3 | `@default` : 默认值, 值只能为string|number|boolean|null。 4 | 5 | ## 语法 6 | 7 | > `@default []` 8 | -------------------------------------------------------------------------------- /php/internal/outer.php: -------------------------------------------------------------------------------- 1 | "@author" : 当前文件的作者

5 | * 6 | * @author 应杲臻 7 | */ 8 | class TagAuthor 9 | { 10 | } 11 | -------------------------------------------------------------------------------- /javascript/default/demo.js: -------------------------------------------------------------------------------- 1 | const config = { 2 | /** 3 | * @default 4 | */ 5 | enable : true, 6 | 7 | /** 8 | * @default 9 | */ 10 | headers : 'x-forwarded-proto', 11 | }; 12 | -------------------------------------------------------------------------------- /php/author/README.md: -------------------------------------------------------------------------------- 1 | @author 2 | ======= 3 | 4 | `@author` : 当前文件的作者. 5 | 6 | 语法 7 | ======= 8 | 9 | > `@author [name] []` 10 | 11 | 描述 12 | ======= 13 | 14 | - `@author`可以后边包含作者电子邮箱，通常电子邮箱由<>包裹 15 | -------------------------------------------------------------------------------- /javascript/member/demo.js: -------------------------------------------------------------------------------- 1 | const config = { 2 | /** 3 | * @member {Array} 4 | */ 5 | array : [], 6 | }; 7 | 8 | // FIXME.@member定义类型为{Array},但是实际赋值类型为{String},会产生一个警告 9 | config.array = 'not array'; 10 | -------------------------------------------------------------------------------- /javascript/inheritdoc/README.md: -------------------------------------------------------------------------------- 1 | # @inheritdoc 2 | 3 | `@inheritdoc` : 指明这个标识应继承其父类的文档。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 语法 8 | 9 | > `@inheritdoc` 10 | 11 | ## 标签效果 12 | 13 | ![demo.jpg](./docs/demo.png) -------------------------------------------------------------------------------- /javascript/deprecated/demo1.js: -------------------------------------------------------------------------------- 1 | /** 2 | * "@deprecated" : 被此标记的函数或者成员方法表示下个版本将会被废弃，告知适用方不再推荐使用此方法 3 | */ 4 | 5 | /** 6 | * 表示此方法将在未来会被废弃 7 | * 8 | * @deprecated 9 | */ 10 | function willBeDeprecated() 11 | { 12 | } 13 | willBeDeprecated(); 14 | -------------------------------------------------------------------------------- /javascript/constructor/demo.js: -------------------------------------------------------------------------------- 1 | /** 2 | * "@constructor" : 构造函数 3 | */ 4 | 5 | /** 6 | * @constructor 7 | */ 8 | function TagConstructor() 9 | { 10 | } 11 | // PASS. 12 | new TagConstructor(); 13 | 14 | // WARN.由于被标记为构造函数，所以应该`new`进行实例化 15 | TagConstructor(); 16 | -------------------------------------------------------------------------------- /php/throws/README.md: -------------------------------------------------------------------------------- 1 | @throws 2 | ======= 3 | 4 | `@throws` : 抛出一个异常，告诉调用方需要做好处理异常相关工作. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@throws [Type] []` 12 | 13 | 14 | 标签效果 15 | ======= 16 | 17 | ![demo.jpg](./docs/demo.png) 18 | -------------------------------------------------------------------------------- /javascript/see/demo.js: -------------------------------------------------------------------------------- 1 | /** 2 | * "@see" : URL跳转 3 | * 4 | * @constructor 5 | * @see http://www.baidu.com 6 | */ 7 | function Foo() { 8 | this.bar = null; 9 | } 10 | 11 | /** 12 | * "@see" : 内部资源跳转 13 | * 14 | * @constructor 15 | * @see {Foo#bar} 16 | */ 17 | function bar() {} 18 | -------------------------------------------------------------------------------- /javascript/constructor/README.md: -------------------------------------------------------------------------------- 1 | # @constructor 2 | 3 | `@constructor` : 被**constructor**标记的方法会被视为构造函数. 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 语法 8 | 9 | > `@class [ ]` 10 | 11 | ## 别名 12 | 13 | `@class` 14 | 15 | ## 标签效果 16 | 17 | ![demo.jpg](./docs/demo.png) 18 | -------------------------------------------------------------------------------- /javascript/abstract/README.md: -------------------------------------------------------------------------------- 1 | # @abstract 2 | 3 | `@abstract` : 被此标记标识的成员方法，必须在继承成员的对象中实现。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | 别名 : `@virtual` 8 | 9 | # 概述 10 | 该成员（一般指父类的方法）必须在继承的子类中实现（或重写）。 11 | 12 | ## 语法 13 | 14 | > `@abstract` 15 | 16 | ## 标签效果 17 | 18 | ![demo.jpg](./docs/demo.png) 19 | 20 | -------------------------------------------------------------------------------- /javascript/throws/index.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @description 抛出指定错误类型的错误 3 | * @throws {SQLException} 4 | */ 5 | function tagThrows1() { 6 | } 7 | 8 | /** 9 | * @throws SQL Execute failed 10 | */ 11 | function tagThrows2() { 12 | } 13 | 14 | /** 15 | * @throws {SQLException} SQL Execute failed. 16 | */ 17 | function tagThrows3() { 18 | } -------------------------------------------------------------------------------- /javascript/param/demo3.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @description 入参默认值 3 | * 4 | * 此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用 5 | * 6 | * @param {Boolean|null} [enable = true] - 定义入参enable是可选参数，默认值为true 7 | */ 8 | function TagParamByDefault(enable) { 9 | if (enable === null) { 10 | enable = true; 11 | } 12 | } 13 | 14 | TagParamByDefault(); -------------------------------------------------------------------------------- /javascript/returns/demo.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @description 字符串拼接 3 | * @param {String} string1 4 | * @param {String} string2 5 | * @returns {String} 6 | */ 7 | function concat(string1, string2) { 8 | // FIXME. 由@returns标记返回值为string,而实际返回值为number,所以<类型不符>会产生一个告警 9 | return 123; 10 | } 11 | 12 | // FIXME. 由@returns标记返回值为string,而Math.abs入参要求为number,所以<类型不符>会产生一个告警 13 | Math.abs("xxx"); 14 | 15 | -------------------------------------------------------------------------------- /javascript/throws/README.md: -------------------------------------------------------------------------------- 1 | # @throws 2 | 3 | `@throws` : 说明可能会被抛出什么样的错误。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 语法 8 | 9 | - `@throws free-form description` 10 | - `@throws {}` 11 | - `@throws {} free-form description` 12 | 13 | ## 概述 14 | 15 | @throws标签可以让你描述函数可能会抛出的错误。在一个JSDoc注释块中您可以包含多个@throws标签。 16 | 17 | ## 标签效果 18 | 19 | ![demo.jpg](./docs/demo.png) 20 | -------------------------------------------------------------------------------- /javascript/deprecated/demo2.js: -------------------------------------------------------------------------------- 1 | /** 2 | * "@deprecated" : 被此标记的函数或者成员方法表示下个版本将会被废弃，告知适用方不再推荐使用此方法 3 | */ 4 | 5 | /** 6 | * 过气的接口1.0版本,请使用最新接口V2 7 | * 8 | * @see apiV2 9 | * @deprecated 3.0.0 此方法以被废弃，请使用最新方法v2 10 | */ 11 | function apiV1() 12 | { 13 | } 14 | 15 | /** 16 | * V1已经过时了，我就是最靓的V2方法 17 | */ 18 | function apiV2() 19 | { 20 | } 21 | 22 | // WARN. API V1已经被标记deprecated，请使用apiV2 23 | apiV1(); 24 | -------------------------------------------------------------------------------- /javascript/see/README.md: -------------------------------------------------------------------------------- 1 | # @see 2 | 3 | `@see` : 此标签表示可以参考另一个标识符的说明文档，或者一个外部资源。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 语法 8 | 9 | - `@see ` 10 | - `@see ` 11 | 12 | ## 标签效果 13 | 14 | 动图演示内容 15 | 16 | - 通过@see标记的{Foo#bar}，可以进行跳转到Foo类中的bar成员属性中 17 | - 通过点击@see标记的外部链接[http://www.baidu.com](http://www.baidu.com)，可跳转到浏览器中查看 18 | 19 | ![demo.jpg](./docs/demo1.gif) 20 | -------------------------------------------------------------------------------- /php/link/index.php: -------------------------------------------------------------------------------- 1 | "@link" : 可用作于跳转到外部链接

5 | * 6 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 7 | */ 8 | class Image 9 | { 10 | /** 11 | * <1>.引导外部跳转链接 12 | * 13 | * @link https://www.baidu.com 14 | * @return string 15 | */ 16 | public static function buildBaiduUrl() 17 | { 18 | return 'https://www.baidu.com'; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /php/internal/README.md: -------------------------------------------------------------------------------- 1 | @internal 2 | ======= 3 | 4 | `@internal` : 被此标签标记的内部类/方法，作用范围只能限于当前文件，外部文件不可调用. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@internal [description]` 12 | 13 | 使用场景 14 | ======= 15 | 16 | 此标签通常可使用在单元测试中，比如在单元测试中定义了一个测试用的类，可对此测试类添加`@internal`标签，这样别人在正常逻辑中万一不小心错误引用了测试类，在IDE的帮助下，可以第一时间得到反馈. 17 | 18 | 标签效果 19 | ======= 20 | ![demo.jpg](./docs/demo.jpg) 21 | -------------------------------------------------------------------------------- /javascript/abstract/demo.js: -------------------------------------------------------------------------------- 1 | /** 2 | * "@abstract" : 被此标记标识的成员方法，必须在继承成员的对象中实现。 3 | */ 4 | class TagAbstract { 5 | /** 6 | * 一个抽象方法，需要待实现 7 | * 8 | * @abstract 9 | */ 10 | methodNeedImplements() { 11 | throw new Error('You have to implement the this methods') 12 | } 13 | } 14 | 15 | class TagAbstractSon extends TagAbstract { 16 | } 17 | 18 | 19 | 20 | new TagAbstractSon(); 21 | -------------------------------------------------------------------------------- /javascript/deprecated/README.md: -------------------------------------------------------------------------------- 1 | # @deprecated 2 | 3 | `@deprecated` : 被此标记的函数或者成员方法表示下个版本将会被废弃，告知适用方不再推荐使用此方法. 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 语法 8 | 9 | > `@deprecated []` 10 | 11 | ## 描述 12 | 13 | - 如果被标记的方法只是因为被其他新方法代替而被废弃，可以结合`@see`来表示被代替的方法 14 | 15 | ## 标签效果 16 | 17 | ### 废弃标签 18 | ![demo1.jpg](./docs/demo1.png) 19 | 20 | ### 搭配@see 21 | ![demo2.jpg](./docs/demo2.png) 22 | -------------------------------------------------------------------------------- /javascript/param/demo2.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @description 如果函数的入参是一个对象，可以定义入参对象属性类型 3 | * 4 | * 此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用 5 | * 6 | * @param {string} people.name - 名字 7 | * @param {number} people.age - 年龄 8 | */ 9 | function TagParam(people) { 10 | // PASS 11 | Math.abs(people.age); 12 | 13 | // FIXME. @param定义people.name类型为string，而Math.abs要求入参是number,所以会产生一个告警 14 | Math.abs(people.name); 15 | } 16 | -------------------------------------------------------------------------------- /php/deprecated/README.md: -------------------------------------------------------------------------------- 1 | @deprecated 2 | ======= 3 | 4 | `@deprecated` : 被此标记的函数或者成员方法表示下个版本将会被废弃，告知适用方不再推荐使用此方法. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@deprecated [] []` 12 | 13 | 描述 14 | ======= 15 | 16 | - `@deprecated`可以填写一个版本号，版本号的规则同`@version` 17 | - 如果被标记的方法只是因为被其他新方法代替而被废弃，可以结合`@see`来表示被代替的方法 18 | 19 | 标签效果 20 | ======= 21 | ![demo.jpg](./docs/demo.jpg) 22 | -------------------------------------------------------------------------------- /php/inheritdoc/README.md: -------------------------------------------------------------------------------- 1 | @inheritdoc 2 | ======= 3 | 4 | `@inheritdoc` : 文档继承,会继承父类的文档注释. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@inheritDoc` 12 | 13 | 描述 14 | ======= 15 | 16 | - `@inheritDoc`会继承父类的所有文档注释.在继承之后可以对指定字段进行重写 17 | 18 | 标签效果 19 | ======= 20 | 21 | 1.直接继承 22 | ======= 23 | 24 | ![demo1.jpg](./docs/demo1.jpg) 25 | 26 | 2.继承重写 27 | ======= 28 | 29 | ![demo2.jpg](./docs/demo2.jpg) 30 | -------------------------------------------------------------------------------- /javascript/type/demo2.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @classdesc 为一个普通变量定义类型 3 | * 4 | * 此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用 5 | */ 6 | 7 | class HelloType { 8 | /** 9 | * @public 10 | */ 11 | hello() { 12 | } 13 | } 14 | 15 | // 这里我们定义一个未知类型的变量，但通过注释对其指定变量 16 | /** @type {HelloType} tag */ 17 | let tag; 18 | 19 | // PASS. {HelloType}里包含了成员方法hello 20 | tag.hello(); 21 | 22 | 23 | // FIXME.因为变量tag被@type定义成{HelloType}类型，而{HelloType}不包含world成员方法.所以会产生一个告警 24 | tag.world(); 25 | -------------------------------------------------------------------------------- /php/link/README.md: -------------------------------------------------------------------------------- 1 | @link 2 | ======= 3 | 4 | `@link` : 此标签可以引导你到指定的**外部跳转链接**. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@link [URI] []` 12 | 13 | 描述 14 | ======= 15 | 16 | 该标签只有1个跳转选项 17 | 18 | - `@外部跳转链接` : 必须是满足[RFC2396](https://www.ietf.org/rfc/rfc2396.txt)的跳转链接,例如[http://github.com/yinggaozhen](http://github.com/yinggaozhen) 19 | 20 | 和@see的区别 21 | ======= 22 | 23 | | - | @see | @link | 24 | |---|---|---| 25 | |外部链接 | √ | √ | 26 | |内部程序 | √ | X | 27 | 28 | -------------------------------------------------------------------------------- /javascript/param/demo1.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @description 为函数入参定义类型 3 | * 4 | * 此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用 5 | * 6 | * @param {string} stringVar - 字符串 7 | * @param {Array.} arrayVar - 字符串数组 8 | */ 9 | function TagParam(stringVar, arrayVar) { 10 | // FIXME. @param定义arrayVar是{Array.}，所以在push一个{number}类型的变量时，因<类型不符>会产生一个告警 11 | arrayVar.push(123); 12 | } 13 | 14 | // PASS. 15 | TagParam("123456", []); 16 | 17 | // FIXME. @param定义stringVar类型是{string},而实际入参是{number},因为会产生一个告警 18 | TagParam(123456, ["123456", "456789"]); 19 | 20 | -------------------------------------------------------------------------------- /php/internal/index.php: -------------------------------------------------------------------------------- 1 | "@internal" : 内部类/方法，只能作用于当前文件，外部文件不可调用

5 | * 6 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 7 | */ 8 | class TagInternal 9 | { 10 | function proxy() 11 | { 12 | // PASS. 当前文件可调用 13 | // 错误调用方法可查看outer.php 14 | return TagInternalClass::invoke(); 15 | } 16 | } 17 | 18 | /** 19 | * 内部类，只允许当前文件使用，外部文件不可使用 20 | * 21 | * @internal 22 | */ 23 | class TagInternalClass 24 | { 25 | public static function invoke() 26 | { 27 | return 'Hello Guozhen'; 28 | } 29 | } 30 | -------------------------------------------------------------------------------- /php/see/README.md: -------------------------------------------------------------------------------- 1 | @see 2 | ======= 3 | 4 | `@see` : 此标签可以引导你到指定的**外部跳转链接**/**内部程序**. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@see [URI | FQSEN] []` 12 | 13 | 描述 14 | ======= 15 | 16 | 该标签可以有两个跳转选项 17 | 18 | - `@外部跳转链接` : 必须是满足[RFC2396](https://www.ietf.org/rfc/rfc2396.txt)的跳转链接,例如[http://github.com/yinggaozhen](http://github.com/yinggaozhen) 19 | - `@内部程序链接` : 可以跳转到制定的类/方法/变量，如class::method 20 | 21 | 和@link的区别 22 | ======= 23 | 24 | | - | @see | @link | 25 | |---|---|---| 26 | |外部链接 | √ | √ | 27 | |内部程序 | √ | X | 28 | 29 | -------------------------------------------------------------------------------- /php/see/index.php: -------------------------------------------------------------------------------- 1 | "@see" : 可用作于跳转到外部链接/内部程序跳转

5 | * 6 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 7 | */ 8 | class TagSee 9 | { 10 | /** 11 | * <1>.引导外部跳转链接 12 | * 13 | * @see https://www.baidu.com 14 | * @return string 15 | */ 16 | public static function buildBaiduUrl() 17 | { 18 | return 'https://www.baidu.com'; 19 | } 20 | 21 | /** 22 | * <2>.引导到内部程序 23 | * 24 | * @see TagSee::buildBaiduUrl 25 | */ 26 | public static function urlProxy() 27 | { 28 | } 29 | } 30 | -------------------------------------------------------------------------------- /php/throws/index.php: -------------------------------------------------------------------------------- 1 | "@throws" : 抛出一个异常，告诉调用方需要做好处理异常相关工作

5 | * 6 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 7 | */ 8 | class TagThrows 9 | { 10 | /** 11 | * 整数相除 12 | * 13 | * @param integer $a 14 | * @param integer $b 15 | * @return float|int 16 | * @throws \Exception 被除数不能为0 17 | */ 18 | public static function div($a, $b) 19 | { 20 | if (empty($b)) { 21 | throw new Exception('Division by zero'); 22 | } 23 | 24 | return $a / $b; 25 | } 26 | } 27 | 28 | echo TagThrows::div(1, 2); 29 | -------------------------------------------------------------------------------- /php/property/index.php: -------------------------------------------------------------------------------- 1 | "@property" : 当类中包含魔术方法__get/__set时，可以通过此标签定义名称

5 | *

类型可查看README.md

6 | * 7 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 8 | * 9 | * @property int $intVar 数字 10 | * @property string $stringVar 字符串 11 | * @property mixed $any 任意类型返回值 12 | */ 13 | class TagProperty 14 | { 15 | public function __get($name) 16 | { 17 | } 18 | 19 | public function __set($name, $value) 20 | { 21 | } 22 | } 23 | 24 | $tag = new TagProperty(); 25 | 26 | // PASS. 27 | $tag->any = 2; 28 | // WARN.hello未在@property中定义 29 | $tag->hello = 2; 30 | -------------------------------------------------------------------------------- /php/method/README.md: -------------------------------------------------------------------------------- 1 | @method 2 | ======= 3 | 4 | `@method` : 此标签可告诉类有哪些魔术方法可以调用. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@method [modifier] [return type] [name]([[type] [parameter]<, …>]) []` 12 | 13 | 使用场景 14 | ======= 15 | 当一个类用魔术方法`__call`去代理执行类成员方法时，对于调用方来讲是很迷茫的，因为调用方是无法知道具体有哪些方法可以调用. 16 | 通过引入`@method`可以解决这个问题，可以在类注释添加`@method`，定义魔术方法可调用的方法，这样调用法可以通过查看注释即可知道如何调用魔术方法，部分IDE可直接识别`@method`标签从而实现自动填充以及类型判断． 17 | 18 | 标签效果 19 | ======= 20 | 21 | IDE自动提示 22 | ======= 23 | 24 | ![demo.jpg](./docs/demo1.jpg) 25 | 26 | 最终效果 27 | ======= 28 | 29 | ![demo.jpg](./docs/demo2.jpg) 30 | -------------------------------------------------------------------------------- /php/param/index.php: -------------------------------------------------------------------------------- 1 | "@param" : 可以记录函数/方法的单个入参的信息

5 | *

完整类型可查看README.md

6 | * 7 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 8 | */ 9 | class TagParam 10 | { 11 | /** 12 | * @param string[] $collection 集合 13 | * @param string $piece 碎片 14 | * @return string[] 15 | */ 16 | public static function join($collection, $piece) 17 | { 18 | $collection[] = $piece; 19 | 20 | return $collection; 21 | } 22 | } 23 | 24 | // PASS. 25 | TagParam::join([], 'hello'); 26 | // WARN. @param规定第一入参类型为string[]，但是实际入参类型为number 27 | TagParam::join(123, 'hello'); 28 | -------------------------------------------------------------------------------- /javascript/type/demo1.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @classdesc 为成员变量定义类型 3 | * 4 | * 此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用 5 | * 6 | * @constructor 7 | */ 8 | function TagType() { 9 | /** 10 | * @type {*} 11 | */ 12 | this.anyProperty = null; 13 | 14 | /** 15 | * @type {string} 16 | */ 17 | this.stringProperty = ''; 18 | 19 | /** 20 | * @type {Array.} 21 | */ 22 | this.arrayProperty = []; 23 | } 24 | 25 | let tag = new TagType(); 26 | 27 | tag.arrayProperty.push("123456"); 28 | 29 | // FIXME.@type定义arrayProperty是字符串类型数组，所以在push一个数字类型的变量时,会产生一个告警 30 | tag.arrayProperty.push(123456); 31 | 32 | -------------------------------------------------------------------------------- /php/var/index.php: -------------------------------------------------------------------------------- 1 | "@var" : 定义一个数据的类型

5 | *

完整类型可查看README.md

6 | * 7 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 8 | */ 9 | class TagVar 10 | { 11 | /** 12 | * <1>.第一种使用方法，只定义类型，通常用于类成员变量中 13 | * 14 | * @var array|null 标签数组 15 | */ 16 | public $tags = null; 17 | } 18 | 19 | $tag = new TagVar(); 20 | // WARN.因为@var定义了这个参数类型是string，所以字符串函数strlen产生警告 21 | strlen($tag->tags); 22 | 23 | // =========================== 第二种定义方法 ================================ 24 | 25 | /** 26 | * <2>.第二种使用方法，给指定变量指定类型 27 | * 28 | * @var array $tags 标签数组 29 | */ 30 | // WARN.因为@var定义$tags的参数类型是array，所以字符串函数strlen产生警告 31 | strlen($tags); 32 | -------------------------------------------------------------------------------- /php/return/README.md: -------------------------------------------------------------------------------- 1 | @return 2 | ======= 3 | 4 | `@return` : 用于在函数/方法返回值信息. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@return [Type] []` 12 | 13 | 变量列表 14 | ======= 15 | | 变量类型 | 说明 | 16 | |---|---| 17 | |string | 字符串| 18 | |integer/int | number/int类型 | 19 | |boolean/bool | false/true | 20 | |float/double | number/浮点数 | 21 | |object | 对象实例| 22 | |specifiedType | 指定类 | 23 | |mixed | 任意类型| 24 | |array/specifiedType[] | 数组，可以指定成指定类型的数组| 25 | |resource | 文件资源类型| 26 | |void | 无返回值| 27 | |null | -| 28 | |callable | 可执行的回调函数| 29 | |function | 不一定能执行的方法| 30 | |self/$this | 当前实例| 31 | 32 | 标签效果 33 | ======= 34 | 35 | ![demo.jpg](./docs/demo.png) 36 | -------------------------------------------------------------------------------- /php/param/README.md: -------------------------------------------------------------------------------- 1 | @param 2 | ======= 3 | 4 | `@param` : 可以记录函数/方法的单个入参的信息. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@param [Type] [name] []` 12 | 13 | 变量列表 14 | ======= 15 | | 变量类型 | 说明 | 16 | |---|---| 17 | |string | 字符串| 18 | |integer/int | number/int类型 | 19 | |boolean/bool | false/true | 20 | |float/double | number/浮点数 | 21 | |object | 对象实例| 22 | |specifiedType | 指定类 | 23 | |mixed | 任意类型| 24 | |array/specifiedType[] | 数组，可以指定成指定类型的数组| 25 | |resource | 文件资源类型| 26 | |void | 无返回值| 27 | |null | -| 28 | |callable | 可执行的回调函数| 29 | |function | 不一定能执行的方法| 30 | |self/$this | 当前实例| 31 | 32 | 标签效果 33 | ======= 34 | 35 | ![demo.jpg](./docs/demo.png) 36 | -------------------------------------------------------------------------------- /javascript/this/index.js: -------------------------------------------------------------------------------- 1 | 2 | 'use strict'; 3 | 4 | /** 5 | * @desc 例子 - 替换上下文 6 | * @link http://usejsdoc.org/tags-this.html 7 | */ 8 | 9 | class ClassForThisOne { 10 | 11 | /** 12 | * Method for replaceContext 13 | */ 14 | replaceContext() { 15 | // ... 16 | } 17 | } 18 | 19 | class ClassForThisTwo { 20 | 21 | /** 22 | * Method for replaceContext 23 | */ 24 | replaceContext() { 25 | // ... 26 | } 27 | } 28 | 29 | /** 30 | * 表示此函数的上下文为 : ClassForThisOne 31 | * 加入{@this}，则IDE认为`replaceContext`只属于ClassForThisOne，能让代码更加清晰 32 | * 33 | * @function 34 | * @this {ClassForThisOne} 35 | */ 36 | function FunctionForThis() { 37 | this.replaceContext(); 38 | } 39 | 40 | FunctionForThis.apply(new ClassForThisOne()); -------------------------------------------------------------------------------- /php/method/index.php: -------------------------------------------------------------------------------- 1 | "@method" : 此标签可告诉类有哪些魔术方法可以调用

5 | * 6 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 7 | * 8 | * @method int incr($number, $step = 1) 递增数字 9 | * @method array explode(string $delimiter, string $string) 分割字符串 10 | * @method static void incrStatic($number, $step = 1) 递增数字(静态) 11 | */ 12 | class TagMethod 13 | { 14 | function __call($name, $arguments) 15 | { 16 | } 17 | 18 | static function __callStatic($name, $arguments) 19 | { 20 | } 21 | } 22 | 23 | $tagMethod = new TagMethod(); 24 | 25 | // PASS. 26 | $tagMethod->incr(1); 27 | // PASS. 28 | $tagMethod->explode('|', 'a|b|c'); 29 | // PASS. 30 | $tagMethod::incrStatic(1); 31 | // WARN.因为方法定义第一个入参类型为string,实际传入为array 32 | $tagMethod->explode([], 'a|b|c'); 33 | // WARN.没有用@method申明 34 | $tagMethod->noobMethod(); 35 | -------------------------------------------------------------------------------- /php/var/README.md: -------------------------------------------------------------------------------- 1 | @var 2 | ======= 3 | 4 | `@var` : 定义一个数据的类型. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@var [Type] [$element_name] []` 12 | 13 | 变量列表 14 | ======= 15 | | 变量类型 | 说明 | 16 | |---|---| 17 | |string | 字符串| 18 | |integer/int | number/int类型 | 19 | |boolean/bool | false/true | 20 | |float/double | number/浮点数 | 21 | |object | 对象实例| 22 | |specifiedType | 指定类 | 23 | |mixed | 任意类型| 24 | |array/specifiedType[] | 数组，可以指定成指定类型的数组| 25 | |resource | 文件资源类型| 26 | |void | 无返回值| 27 | |null | -| 28 | |callable | 可执行的回调函数| 29 | |function | 不一定能执行的方法| 30 | |self/$this | 当前实例| 31 | 32 | 标签效果 33 | ======= 34 | 35 | 实现@var可以有两种使用方法 36 | 37 | 1.在类成员变量中定义，不需要指定变量名称 38 | ======= 39 | 40 | ![demo.jpg](./docs/demo1.png) 41 | 42 | 2.直接给具体变量定义，需要指定变量名称 43 | ======= 44 | 45 | ![demo.jpg](./docs/demo2.png) 46 | -------------------------------------------------------------------------------- /javascript/inheritdoc/demo.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @classdesc 指明这个标识应继承其父类的文档 3 | */ 4 | class FatherInheritDoc { 5 | 6 | /** 7 | * 此方法注释被继承 8 | * 9 | * @param {String} string 10 | */ 11 | methodWithInherit(string) { 12 | 13 | } 14 | 15 | /** 16 | * 此方法注释不被继承 17 | * 18 | * @param {String} string 19 | */ 20 | methodWithoutInherit(string) { 21 | 22 | } 23 | } 24 | 25 | class SonInheritDoc extends FatherInheritDoc { 26 | 27 | /** 28 | * @inheritDoc 29 | */ 30 | methodWithInherit(string) { 31 | 32 | } 33 | 34 | methodWithoutInherit(string) { 35 | 36 | } 37 | } 38 | 39 | // 文档没有被继承，即便传入错误参数也不会警告 40 | (new SonInheritDoc()).methodWithoutInherit([]); 41 | 42 | // FIXME. 文档继承之后，第一个入参被认为应当传入string类型，所以传入错误参数会警告 43 | (new SonInheritDoc()).methodWithInherit([1, 2, 3, 4, 5]); 44 | -------------------------------------------------------------------------------- /php/return/index.php: -------------------------------------------------------------------------------- 1 | "@return" : 用于在函数/方法返回值信息

5 | *

完整类型可查看README.md

6 | * 7 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 8 | */ 9 | class TagReturn 10 | { 11 | private static $config = []; 12 | 13 | /** 14 | * <1.> 返回主机名称 15 | * 16 | * @return string 主机名称 17 | */ 18 | public static function getHost() 19 | { 20 | return $_SERVER['host'] ?: '127.0.0.1'; 21 | } 22 | 23 | /** 24 | * <2.> 返回配置信息，如果name为null，返回所有配置 25 | * 26 | * @param string|null $name 配置名称 27 | * @return string|array 主机名称(返回值多类型) 28 | */ 29 | public static function getConfig($name = null) 30 | { 31 | return isset(static::$config[$name]) ? static::$config[$name] : static::$config; 32 | } 33 | } 34 | 35 | $host = TagReturn::getHost(); 36 | // PASS. 37 | strlen($host); 38 | // WARN. TagReturn::getHost返回值定义为string,所以$host用array方法会产生一个警告 39 | array_pop($host); 40 | -------------------------------------------------------------------------------- /php/property/README.md: -------------------------------------------------------------------------------- 1 | @property 2 | ======= 3 | 4 | `@property` : 当类中包含魔术方法__get/__set时，可以通过此标签定义名称. 5 | 6 | **此标签推荐使用PhpStorm进行阅读,可以能直观体现标签的作用** 7 | 8 | 语法 9 | ======= 10 | 11 | > `@property [Type] [name] []` 12 | 13 | 使用场景 14 | ======= 15 | 当一个类用魔术方法`__get`或者`__set`去代理执行类成员变量时，对于调用方来讲是很迷茫的，因为调用方是无法知道具体有哪些成员. 16 | 通过引入`@property`可以解决这个问题，可以在类注释添加`@property`定义成员变量，这样调用法可以通过查看注释即可知道具体有哪些成员变量可以使用，部分IDE可直接识别`@property`标签从而实现自动填充以及类型判断． 17 | 18 | 变量列表 19 | ======= 20 | | 变量类型 | 说明 | 21 | |---|---| 22 | |string | 字符串| 23 | |integer/int | number/int类型 | 24 | |boolean/bool | false/true | 25 | |float/double | number/浮点数 | 26 | |object | 对象实例| 27 | |specifiedType | 指定类 | 28 | |mixed | 任意类型| 29 | |array/specifiedType[] | 数组，可以指定成指定类型的数组| 30 | |resource | 文件资源类型| 31 | |void | 无返回值| 32 | |null | -| 33 | |callable | 可执行的回调函数| 34 | |function | 不一定能执行的方法| 35 | |self/$this | 当前实例| 36 | 37 | 标签效果 38 | ======= 39 | 40 | IDE自动提示 41 | ======= 42 | 43 | ![demo.jpg](./docs/demo1.png) 44 | 45 | 最终效果 46 | ======= 47 | 48 | ![demo.jpg](./docs/demo2.png) 49 | -------------------------------------------------------------------------------- /php/deprecated/index.php: -------------------------------------------------------------------------------- 1 | "@deprecated" : 被此标记的函数或者成员方法表示下个版本将会被废弃，告知适用方不再推荐使用此方法

5 | * 6 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 7 | */ 8 | class TagDeprecated 9 | { 10 | /** 11 | * <1>.表示此方法将在未来会被废弃 12 | * 13 | * @deprecated 14 | */ 15 | public static function willBeDeprecated() 16 | { 17 | } 18 | 19 | /** 20 | * <2>.表示此方法将在未来指定版本会被废弃 21 | * 22 | * @deprecated 1.0.0 23 | */ 24 | public static function willBeDeprecatedNextVersion() 25 | { 26 | } 27 | 28 | /** 29 | * <3>.过气的接口1.0版本,请使用最新接口V2 30 | * 31 | * @see TagDeprecated::apiV2() 32 | * @deprecated 3.0.0 此方法以被废弃，请使用最新方法v2 33 | */ 34 | public static function apiV1() 35 | { 36 | } 37 | 38 | /** 39 | * V1已经过时了，我就是最靓的V2方法 40 | */ 41 | public static function apiV2() 42 | { 43 | } 44 | } 45 | 46 | // 普通标记 47 | TagDeprecated::willBeDeprecated(); 48 | // 标记未来将要废弃的版本 49 | TagDeprecated::willBeDeprecatedNextVersion(); 50 | // 方法因升级而被废弃，需要配合@see标签使用 51 | TagDeprecated::apiV1(); 52 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 Gaozhen Ying 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /javascript/access/index.js: -------------------------------------------------------------------------------- 1 | 2 | 'use strict'; 3 | 4 | /** 5 | * @link http://usejsdoc.org/tags-access.html 6 | * 7 | * @desc 8 | * `@access` : 访问权限,虽然js里对属性类没有访问限制,但是可以通过注释去进行约束. 9 | */ 10 | 11 | class ClassForAccess { 12 | 13 | constructor() { 14 | 15 | /** 16 | * @type {null} 17 | * @public 18 | */ 19 | this.publicProperty = null; 20 | 21 | /** 22 | * @type {null} 23 | * @protected 24 | */ 25 | this.protectedProperty = null; 26 | 27 | /** 28 | * @type {null} 29 | * @private 30 | */ 31 | this.privatePerperty = null; 32 | } 33 | 34 | /** 35 | * @public 36 | */ 37 | publicMethod() { 38 | 39 | } 40 | 41 | /** 42 | * @protected 43 | */ 44 | protectedMethod() { 45 | 46 | } 47 | 48 | /** 49 | * @private 50 | */ 51 | privateMethod() { 52 | 53 | } 54 | } 55 | 56 | const instance = new ClassForAccess(); 57 | 58 | console.log(instance.publicProperty); // ok 59 | console.log(instance.protectedProperty); // warning 60 | console.log(instance.privatePerperty); // warning 61 | 62 | instance.publicMethod(); // ok 63 | instance.protectedMethod(); // warning 64 | instance.privateMethod(); // warning -------------------------------------------------------------------------------- /php/inheritdoc/index.php: -------------------------------------------------------------------------------- 1 | "@inheritdoc" : 文档继承,会继承父类的文档注释，继承之后可以对父类文档进行重写

5 | * 6 | * 此标签建议在PHPStorm中打开此演示文档，可以看到具体的标签效果 7 | */ 8 | class TagInheritdoc 9 | { 10 | /** 11 | * <1>.此方法注释被继承 12 | * 13 | * @param array $array 14 | */ 15 | public function methodWithInherit($array) 16 | { 17 | } 18 | 19 | /** 20 | * <2>.此方法注释被继承，且注释被重写 21 | * 22 | * @param string $string 23 | * @param array $mixed 24 | */ 25 | public function methodWithOverride($string, $mixed) 26 | { 27 | } 28 | } 29 | 30 | class TagInheritdocImpl extends TagInheritdoc 31 | { 32 | /** 33 | * @inheritDoc 34 | */ 35 | public function methodWithInherit($array) 36 | { 37 | } 38 | 39 | /** 40 | * 注释被继承后，重写mixed字段类型为int 41 | * 42 | * @inheritDoc 43 | * @param int $mixed 44 | */ 45 | public function methodWithOverride($string, $mixed) 46 | { 47 | } 48 | } 49 | 50 | // PASS.父类定义文档入参类型为array,继承之后所有注释也都被生效 51 | (new TagInheritdocImpl())->methodWithInherit([]); 52 | // WARN.父类文档注释定义入参为array,但是传入是数字 53 | (new TagInheritdocImpl())->methodWithInherit(123456); 54 | 55 | // PASS.重写之后正确的入参 56 | (new TagInheritdocImpl())->methodWithOverride('', 123); 57 | // WARN.父类定义文档$string入参类型是string，但是实际传入类型为数组 58 | (new TagInheritdocImpl())->methodWithOverride([], 123); 59 | // WARN.父类定义文档$mixed参类型是array，但是子类对$mixed类型重写为int. 60 | (new TagInheritdocImpl())->methodWithOverride('', []); 61 | -------------------------------------------------------------------------------- /javascript/README.md: -------------------------------------------------------------------------------- 1 | # Javascript Doc Demo 2 | 3 | Javascript注释标签范例，每个标签我都制作了**相关图文信息**，助你能更好理解每个注释标签的作用 4 | 5 | [![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/yinggaozhen/doc-demo/blob/master/LICENSE) 6 | 7 | :heart::heart::heart:标签会不定期持续更新，欢迎各位**fork & star**:heart::heart::heart: 8 | 9 | ## [Javascript相关注释标签](https://github.com/yinggaozhen/doc-demo/tree/master/javascript) 10 | 11 | |||||| 12 | |---|---|---|---|---| 13 | |[@abstract](./abstract)|@access|[@constructor](./constructor)|[@default](./default)|[@deprecated](./deprecated)| 14 | |@example|[@inheritdoc](./inheritdoc)|@link|[@member](./member)|[@param](./param)| 15 | |[@returns](./returns)|[@see](./see)|@this|[@throws](./throws)|[@type](./type)| 16 | | @copyright | @license| @since |@author |@todo | 17 | | @global | @ignore| @file |@implements |@memberOf | 18 | | @exports | @mixes| @mixin |@module | @namespace| 19 | | @override | @static| @typedef |@version | @requires| 20 | 21 | ## 阅读姿势 22 | 23 | 你可以采用以下两种方法查阅 24 | 25 | ### 1. 安装浏览器扩展octotree 26 | 27 | 需要在浏览器上安装对应的github阅读插件**octotree**，安装成功之后重新刷新github工程即可. 28 | 29 | **插件下载地址** 30 | 31 | - chrome : [https://chrome.google.com/webstore/detail/octotree](https://chrome.google.com/webstore/detail/octotree/bkhaagjahfmjljalopjnoealnfndnagc) 32 | - firefox : [https://addons.mozilla.org/en-US/firefox/addon/octotree/](https://addons.mozilla.org/en-US/firefox/addon/octotree/) 33 | 34 | ### 2. Jetbrains全家桶 35 | 36 | 所谓[Jetbrains](https://www.jetbrains.com/)全家桶，即`PHP -> PhpStorm`， `Javascript -> (PhpStorm/WebStorm)`. 37 | 38 | 理由是强大的**Jetbrains**已经很贴心为我们集成各个语言的标签识别，可以更快速的帮助我们理解每个标签的含义. 39 | 40 | 当然如果你觉得**Jetbrains**全家桶过于臃肿，也没关系，我们为每个标签都制作了详细的**图文信息**，放置于每个标签下的README. 41 | 42 | *毕竟注释标签只是各个语言各自约定一套通用规则，无关乎于IDE* 43 | 44 | ## 相关参考资料 45 | 46 | - JsDoc : [http://www.dba.cn/book/jsdoc/](http://www.dba.cn/book/jsdoc/) 47 | 48 | ## 特别感谢 49 | 50 | 感谢以下同学给出的宝贵意见与指导 51 | 52 | - @czewail 53 | -------------------------------------------------------------------------------- /php/README.md: -------------------------------------------------------------------------------- 1 | # PHP Doc Demo 2 | 3 | PHP注释标签范例，每个标签我都制作了**相关图文信息**，助你能更好理解每个注释标签的作用 4 | 5 | [![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/yinggaozhen/doc-demo/blob/master/LICENSE) 6 | 7 | :heart::heart::heart:标签会不定期持续更新，欢迎各位**fork & star**:heart::heart::heart: 8 | 9 | ## PHP相关标签 10 | 11 | |||||| 12 | |---|---|---|---|---| 13 | |[@author](./author)|[@deprecated](./deprecated)|@example|[@inheritdoc](./inheritdoc)|[@link](./link)| 14 | |[@method](./method)|@mixin|[@param](./param)|[@property](./property)|[@return](./return)| 15 | |[@see](./see)|[@throws](./throws)|[@var](./var)|[@internal](./internal)|@version| 16 | | @copyright | @license| @since |@package |@todo | 17 | 18 | ## PHP注释规范 19 | - 对于引用了全局变量的函数，必须使用@glboal标记 20 | - 对于变量，必须用[@var](./var)标记其类型(int,string,bool…) 21 | - 函数必须通过[@param](./param)和[@return](./return)标记指明其参数和返回值 22 | - 对于出现两次或两次以上的关键字，要通过@ingore忽略掉多余的，只保留一个即可 23 | - 调用了其他函数或类的地方，要使用[@link](./link)或其他标记链接到相应的部分，便于文档的阅读。 24 | - 必要的地方使用非文档性注释，提高代码易读性。 25 | - 描述性内容尽量简明扼要，尽可能使用短语而非句子。 26 | - 全局变量，静态变量和常量必须用相应标记说明 27 | 28 | ## 阅读姿势 29 | 30 | 你可以采用以下两种方法查阅 31 | 32 | ### 1. 安装浏览器扩展octotree 33 | 34 | 需要在浏览器上安装对应的github阅读插件**octotree**，安装成功之后重新刷新github工程即可. 35 | 36 | **插件下载地址** 37 | 38 | - chrome : [https://chrome.google.com/webstore/detail/octotree](https://chrome.google.com/webstore/detail/octotree/bkhaagjahfmjljalopjnoealnfndnagc) 39 | - firefox : [https://addons.mozilla.org/en-US/firefox/addon/octotree/](https://addons.mozilla.org/en-US/firefox/addon/octotree/) 40 | 41 | ### 2. 使用Jetbrains全家桶阅读 42 | 43 | 所谓[Jetbrains](https://www.jetbrains.com/)全家桶，即`PHP -> PhpStorm`， `Javascript -> (PhpStorm/WebStorm)`. 44 | 45 | 理由是强大的**Jetbrains**已经很贴心为我们集成各个语言的标签识别，可以更快速的帮助我们理解每个标签的含义. 46 | 47 | 当然如果你觉得**Jetbrains**全家桶过于臃肿，也没关系，我们为每个标签都制作了详细的**图文信息**，放置于每个标签下的README. 48 | 49 | *毕竟注释标签只是各个语言各自约定一套通用规则，无关乎于IDE* 50 | 51 | ## 相关参考资料 52 | 53 | - PHPDoc : [https://docs.phpdoc.org/](https://docs.phpdoc.org/) 54 | 55 | ## 特别感谢 56 | 57 | 感谢以下同学给出的宝贵意见与指导 58 | 59 | - @popo1h 60 | -------------------------------------------------------------------------------- /javascript/member/README.md: -------------------------------------------------------------------------------- 1 | # @member 2 | 3 | `@member` : 可以为某个成员变量定义类型.可以选择性为成员变量指定名称。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 别名 8 | 9 | `@var` 10 | 11 | ## 语法 12 | 13 | > `@member [] []` 14 | 15 | ## type类型 16 | 17 | ## type基础类型 18 | | 类型 | 说明 | 19 | |---|---| 20 | |string | 字符串 | 21 | |Array or Type[] | 数组 | 22 | |number | 数字 | 23 | |Object | 对象| 24 | |Class | 自定义的类名| 25 | |Function | 方法类型| 26 | |null | -| 27 | |* | 任意类型| 28 | 29 | ## type格式 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 |
类型名语法示例描述
Symbol name{boolean}
{myNamespace.MyClass}		指定符号的名称。 如果标识符已经被文档化，JSDoc将创建一个链接到该标识符的文档
Multiple types{number|boolean}
表示数字或布尔		这意味着值可能是几种类型中的一种，并用|分隔类型的完整列表。
Arrays{Array.string} or string[]
表示字符串数组		-
Objects{name: string, age : number} or Object-
Nullable type一个数字或null {?number}指明类型为指定的类型，或者为null。
Non-nullable type一个数字，但是绝对不会是null {!number} 指明类型为指定的类型，但是绝对不会是null。
Variable number of that type此函数接受可变数量的数值参数。
@param {...number} num 		表示该函数接受可变数量的参数，并指定一个类型的参数
Optional parameter一个可选参数
@param {number} [foo]
@param {number} [foo=1] 可选参数，默认值=1		指示参数是可选的。当使用JSDoc的语法表示可选参数时，你还可以指明参数的默认值。
78 | 79 | 80 | ## 标签效果 81 | 82 | ![demo.jpg](./docs/demo.png) 83 | -------------------------------------------------------------------------------- /javascript/returns/README.md: -------------------------------------------------------------------------------- 1 | # @returns 2 | 3 | `@returns` : 记录一个函数的返回值。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 别名 8 | `@return` 9 | 10 | ## 语法 11 | 12 | > `@return {type} {desc}` 13 | 14 | ## 概述 15 | 16 | @returns 标签描述一个函数的返回值。语法和[@param](../param)类似。 17 | 18 | ## type基础类型 19 | | 类型 | 说明 | 20 | |---|---| 21 | |string | 字符串 | 22 | |Array or Type[] | 数组 | 23 | |number | 数字 | 24 | |Object | 对象| 25 | |Class | 自定义的类名| 26 | |Function | 方法类型| 27 | |null | -| 28 | |* | 任意类型| 29 | 30 | ## type格式 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 |
类型名语法示例描述
Symbol name{boolean}
{myNamespace.MyClass}		指定符号的名称。 如果标识符已经被文档化，JSDoc将创建一个链接到该标识符的文档
Multiple types{number|boolean}
表示数字或布尔		这意味着值可能是几种类型中的一种，并用|分隔类型的完整列表。
Arrays{Array.string} or string[]
表示字符串数组		-
Objects{name: string, age : number} or Object-
Nullable type一个数字或null {?number}指明类型为指定的类型，或者为null。
Non-nullable type一个数字，但是绝对不会是null {!number} 指明类型为指定的类型，但是绝对不会是null。
Variable number of that type此函数接受可变数量的数值参数。
@param {...number} num 		表示该函数接受可变数量的参数，并指定一个类型的参数
Optional parameter一个可选参数
@param {number} [foo]
@param {number} [foo=1] 可选参数，默认值=1		指示参数是可选的。当使用JSDoc的语法表示可选参数时，你还可以指明参数的默认值。
79 | 80 | ## 标签效果 81 | 82 | ![demo.jpg](./docs/demo1.png) 83 | 84 | ![demo.jpg](./docs/demo2.png) 85 | -------------------------------------------------------------------------------- /javascript/param/README.md: -------------------------------------------------------------------------------- 1 | # @param 2 | 3 | `@param` : 标签提供了对某个函数的参数的各项说明，包括参数名、参数数据类型、描述等。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 语法 8 | 9 | > `@param {type} {name} {desc}` 10 | 11 | ## 概述 12 | 13 | @param标签要求您指定要描述参数的名称。您还可以包含参数的数据类型，使用大括号括起来，和参数的描述。 14 | 15 | 类型表达式可以有以下几种表达形式 16 | 17 | - 标识符的namepath(例如，myNamespace.MyClass) 18 | - 一个内置的javascript类型(如string, number) 19 | - 以上两种的组合 20 | 21 | ## type基础类型 22 | | 类型 | 说明 | 23 | |---|---| 24 | |string | 字符串 | 25 | |Array or Type[] | 数组 | 26 | |number | 数字 | 27 | |Object | 对象| 28 | |Class | 自定义的类名| 29 | |Function | 方法类型| 30 | |null | -| 31 | |* | 任意类型| 32 | 33 | ## type格式 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 |
类型名语法示例描述
Symbol name{boolean}
{myNamespace.MyClass}		指定符号的名称。 如果标识符已经被文档化，JSDoc将创建一个链接到该标识符的文档
Multiple types{number|boolean}
表示数字或布尔		这意味着值可能是几种类型中的一种，并用|分隔类型的完整列表。
Arrays{Array.string} or string[]
表示字符串数组		-
Objects{name: string, age : number} or Object-
Nullable type一个数字或null {?number}指明类型为指定的类型，或者为null。
Non-nullable type一个数字，但是绝对不会是null {!number} 指明类型为指定的类型，但是绝对不会是null。
Variable number of that type此函数接受可变数量的数值参数。
@param {...number} num 		表示该函数接受可变数量的参数，并指定一个类型的参数
Optional parameter一个可选参数
@param {number} [foo]
@param {number} [foo=1] 可选参数，默认值=1		指示参数是可选的。当使用JSDoc的语法表示可选参数时，你还可以指明参数的默认值。
82 | 83 | ## 标签效果 84 | 85 | ### 函数入参定义类型 86 | 87 | ![demo.jpg](./docs/demo1.png) 88 | 89 | ### 函数的入参是一个对象，可以定义入参对象属性类型 90 | 91 | ![demo.jpg](./docs/demo2.png) 92 | -------------------------------------------------------------------------------- /javascript/type/README.md: -------------------------------------------------------------------------------- 1 | # @type 2 | 3 | `@type` : 记录一个对象的类型。 4 | 5 | **此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用** 6 | 7 | ## 语法 8 | 9 | > `@type {typeName}` 10 | 11 | ## 概述 12 | 13 | 类型表达式可以有以下几种表达形式 14 | 15 | - 标识符的namepath(例如，myNamespace.MyClass) 16 | - 一个内置的javascript类型(如string, number) 17 | - 以上两种的组合 18 | 19 | ## type基础类型 20 | | 类型 | 说明 | 21 | |---|---| 22 | |string | 字符串 | 23 | |Array or Type[] | 数组 | 24 | |number | 数字 | 25 | |Object | 对象| 26 | |Class | 自定义的类名| 27 | |Function | 方法类型| 28 | |null | -| 29 | |* | 任意类型| 30 | 31 | ## type格式 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 |
类型名语法示例描述
Symbol name{boolean}
{myNamespace.MyClass}		指定符号的名称。 如果标识符已经被文档化，JSDoc将创建一个链接到该标识符的文档
Multiple types{number|boolean}
表示数字或布尔		这意味着值可能是几种类型中的一种，并用|分隔类型的完整列表。
Arrays{Array.string} or string[]
表示字符串数组		-
Objects{name: string, age : number} or Object-
Nullable type一个数字或null {?number}指明类型为指定的类型，或者为null。
Non-nullable type一个数字，但是绝对不会是null {!number} 指明类型为指定的类型，但是绝对不会是null。
Variable number of that type此函数接受可变数量的数值参数。
@param {...number} num 		表示该函数接受可变数量的参数，并指定一个类型的参数
Optional parameter一个可选参数
@param {number} [foo]
@param {number} [foo=1] 可选参数，默认值=1		指示参数是可选的。当使用JSDoc的语法表示可选参数时，你还可以指明参数的默认值。
80 | 81 | ## 标签效果 82 | 83 | ### @type标记成员变量 84 | ![demo.jpg](./docs/demo1.png) 85 | 86 | ### @type标记普通变量 87 | ![demo.jpg](./docs/demo3.png) 88 | 89 | ### IDE自动填充标记变量 90 | 91 | **合理的通过@type标记，可以让IDE对标记的变量类型自动识别** 92 | **例如识别到一个类，IDE会自动填充类的成员方法.可以有效的提升开发效率** 93 | 94 | ![demo.jpg](./docs/demo2.png) 95 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # DocDemo 2 | 3 | 6 | 7 | 注释标签范例，每个标签我都制作了**相关图文信息**，意在能帮你能更好理解每个注释标签的作用.目前包含了PHP/Javascript(ES5 & ES6). 8 | 9 | **或许你离漂亮的代码，就差一个标签^_^** 10 | 11 | [![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/yinggaozhen/doc-demo/blob/master/LICENSE) 12 | 13 | :heart::heart::heart:标签会不定期持续更新，欢迎各位**fork & star**:heart::heart::heart: 14 | 15 | ## [PHP相关注释标签](https://github.com/yinggaozhen/doc-demo/tree/master/php) 16 | 17 | |||||| 18 | |---|---|---|---|---| 19 | |[@author](./php/author)|[@deprecated](./php/deprecated)|@example|[@inheritdoc](./php/inheritdoc)|[@link](./php/link)| 20 | |[@method](./php/method)|@mixin|[@param](./php/param)|[@property](./php/property)|[@return](./php/return)| 21 | |[@see](./php/see)|[@throws](./php/throws)|[@var](./php/var)|[@internal](./php/internal)|@version| 22 | | @copyright | @license| @since |@package |@todo | 23 | 24 | ## [Javascript相关注释标签](https://github.com/yinggaozhen/doc-demo/tree/master/javascript) 25 | 26 | |||||| 27 | |---|---|---|---|---| 28 | |[@abstract](./javascript/abstract)|@access|[@constructor](./javascript/constructor)|[@default](./javascript/default)|[@deprecated](./javascript/deprecated)| 29 | |@example|[@inheritdoc](./javascript/inheritdoc)|@link|[@member](./javascript/member)|[@param](./javascript/param)| 30 | |[@returns](./javascript/returns)|[@see](./javascript/see)|@this|[@throws](./javascript/throws)|[@type](./javascript/type)| 31 | | @copyright | @license| @since |@author |@todo | 32 | | @global | @ignore| @file |@implements |@memberOf | 33 | | @exports | @mixes| @mixin |@module | @namespace| 34 | | @override | @static| @typedef |@version | @requires| 35 | 36 | ## 阅读姿势 37 | 38 | 你可以采用以下两种方法查阅 39 | 40 | ### 1. 安装浏览器扩展octotree 41 | 42 | 需要在浏览器上安装对应的github阅读插件**octotree**，安装成功之后重新刷新github工程即可. 43 | 44 | **插件下载地址** 45 | 46 | - chrome : [https://chrome.google.com/webstore/detail/octotree](https://chrome.google.com/webstore/detail/octotree/bkhaagjahfmjljalopjnoealnfndnagc) 47 | - firefox : [https://addons.mozilla.org/en-US/firefox/addon/octotree/](https://addons.mozilla.org/en-US/firefox/addon/octotree/) 48 | 49 | ### 2. Jetbrains全家桶 50 | 51 | 所谓[Jetbrains](https://www.jetbrains.com/)全家桶，即`PHP -> PhpStorm`， `Javascript -> (PhpStorm/WebStorm)`. 52 | 53 | 理由是强大的**Jetbrains**已经很贴心为我们集成各个语言的标签识别，可以更快速的帮助我们理解每个标签的含义. 54 | 55 | 当然如果你觉得**Jetbrains**全家桶过于臃肿，也没关系，我们为每个标签都制作了详细的**图文信息**，放置于每个标签下的README. 56 | 57 | *毕竟注释标签只是各个语言各自约定一套通用规则，无关乎于IDE* 58 | 59 | ## 相关参考资料 60 | 61 | - PHPDoc : [https://docs.phpdoc.org/](https://docs.phpdoc.org/) 62 | - JsDoc : [http://www.dba.cn/book/jsdoc/](http://www.dba.cn/book/jsdoc/) 63 | 64 | ## 特别感谢 65 | 66 | 感谢以下同学给出的宝贵意见与指导 67 | 68 | - @popo1h 69 | - @czewail 70 | --------------------------------------------------------------------------------