# 比较简单的内部函数 # 代码部分 class Cat: def __init__(self, new_name): self.name = new_name
在类 C 语言(如 Java 和 JavaScript)中,有两种最常见的括号样式:Allman 样式和 1TBS。...对于构造函数,使用严格模式很重要,因为它可以防止你忘记实例化时使用new操作符。你应该知道你可以在构造函数中返回任何对象。有关使用构造函数的更多提示,请参阅实现构造函数的提示。...在前面的代码中,@param就是一个例子。 HTML 您可以在 JSDoc 注释中自由使用 HTML。例如,显示单词的等宽字体。 类型注释 您可以通过大括号中的类型名称来记录实体的类型。...@constructs 记录方法设置实例数据。如果存在这样的方法,则在该类中记录。 @lends namePath 指定以下对象文字贡献给哪个类。有两种贡献的方式。...网站上有文档: 模块化:@module,@exports,@namespace 自定义类型(用于虚拟实体,如回调,其签名可以由您记录):@typedef,@callback 法律事务:@
JSDoc 工具将扫描你的源代码并为您生成一个 HTML 文档网站(当然,即使你不进行生成,其也被大部分浏览器所识别和支持)。JSDoc 的目的是记录 JavaScript 应用程序或库的 API。...假设你想要记录诸如模块、名称空间、类、方法、方法参数等内容。 JSDoc注释通常应该放在记录代码之前。为了被 JSDoc 解析器识别,每个注释必须以 /** 序列开头。...需要注意的是,在JSDoc中标记参数具有默认值并不会改变函数或方法的实际调用方式,你可以只在注释中写好标记的默认参数,而不写在代码中,反之亦然(君子协定)。...myFunction(name='', type='default') { // 函数实现}加餐:不使用类型别名指明对象内参数例如指明某个函数的config对象内的参数,你可以使用嵌套的@property...- 年龄 */function myFunction(config) { // 函数实现}在上面的示例中,我们使用@param标签指明config是一个对象,并且包含两个属性:name和age。
JSDoc语法具有多种用途,包括用类型注释值,为函数指定参数和返回类型,为函数提供文档和使用信息,以及类型错误等。...在一个 .js 文件中添加JSDoc,如所述只是注释,通过使用额外的 * 开启一个注释来完成 // Normal Javascript Comment 1 /* Normal Javascript Comment...通过使用 @typedef 指令可以创建一个对象类型。...改进除法函数,我们可以指定如果除数为零则返回错误,并在代码中处理这种情况。 /** * Divide two numbers....构造函数 类中创建的所有方法和变量 我们使用 @params 关键字来提供需要传递给构造函数的参数的类型和描述。类中的方法与函数的类型方式相同,这在前一节中已经介绍过。
笔记 18 二.支持程度 TypeScript 目前(2019/5/12)仅支持部分 JSDoc 标记,具体如下: @type:描述对象 @param(或@arg或@argument):描述函数参数.../a").x; 注意,这种语法是 TypeScript 特有的(JSDoc 并不支持),而 JSDoc 中采用 ES Module 引入语法: // a.js /** * @typedef State...: number) => boolean 还可以用@typedef特殊语法(仅 TypeScript 支持,JSDoc 里没有)把对象或函数的类型定义整合到一行: /** @typedef {{ prop1...(如{string=})不适用于对象字面量类型,例如@type {{ a: string, b: number= }}是非法的类型声明,可选属性应该用属性名后缀?...具体的,会对构造函数中的this属性访问以及构造函数参数进行检查,并且不允许(不通过new关键字)直接调用构造函数: /** * @constructor * @param {number} data
上面提到的这些,都可以通过 JSDoc 去解决。 你知道的 JSDoc: 国际惯例,先从简单的开始铺垫。...稍微列举下目前我遇到过的问题 •无法支持@private、 @protected这类 tag 修饰,表现在还是在提示中给了出来•无法直接对某个函数定义函数重载,需要依靠对象的形式•很多 tag 不支持,...TS in JS with JSDoc 1.丢失出参类型: 如标题所述。...由于在vue.d.ts里面,传给Vue的options是一个泛型对象,但我们并不能对一个对象使用泛型,因此需要一个helper的函数承接一下,内容很简单: const vueOptionsTypeHelper...怎么去应用 1.对公共组件和全局变量编写声明文件2.对自定义的函数编写 JSDoc 注释,并优雅的完善它3.对作用域不清晰的的变量、对象等使用 JSDoc 的@type,去指定它的类型 注意事项 1.不要瞎用
把鼠标移到 a 处,发现报错是"Type '"123'" is not assignable to type 'number'",也就是说在 TypeScript中这种把字符串 '123' 赋值给数字变量...享受 TypeScript类型系统的好处就是这么简单,不需要改变构建,不需要进行项目的迁移,所需要做的仅仅是在 .js 文件的头部加入 // [@ts-check](/user/ts-check)(前提是你使用的是...} */ let var5; /** * 声明元素类型是数字的数组 - 方式3 * @type {Array} */ let var6; /** * 声明对象类型...string 类型 */ function fn3(p0, p1, p2, p3, p4){ // TODO } /** * 也可以使用模板来声明类型 * 如 fn4 表示返回值和参数 p1...引入 TypeScript来享受类型系统的好处是最简单、学习成本最低的方法。
多亏了 TypeScript和 JSDoc,这两个愿望都有变成现实的可能。...把鼠标移到 a 处,发现报错是"Type '"123'" is not assignable to type 'number'",也就是说在 TypeScript中这种把字符串 '123' 赋值给数字变量...} */ let var5; /** * 声明元素类型是数字的数组 - 方式3 * @type {Array} */ let var6; /** * 声明对象类型...string 类型 */ function fn3(p0, p1, p2, p3, p4){ // TODO } /** * 也可以使用模板来声明类型 * 如 fn4 表示返回值和参数 p1...引入 TypeScript来享受类型系统的好处是最简单、学习成本最低的方法。
里存在大量惯用“模式”,所以在默认类型方面相当宽松,主要表现为 3 点: 函数参数默认可选 未指定的类型参数默认any 类型宽松的对象字面量 函数参数默认可选 .js文件里所有函数参数都默认可选,所以允许实参数量少于形参...定义的泛型,若未指定类型参数,就默认any 类型宽松的对象字面量 .ts里,用对象字面量初始化变量的同时会确定该变量的类型,并且不允许往对象字面量上添加新成员,例如: // .ts // obj 类型为...对于没在构造函数中定义,或者构造函数中类型为undefined或null(此时为any)的属性,其类型为所有赋值中右侧值类型的联合 定义在构造函数中的属性都认为是一定存在的,其它地方(如成员方法)出现的都当作可选的...类声明中未出现的属性都是未定义的,访问就报错 构造函数等价于类 另外,在 ES6 之前,JavaScript 里用构造函数代替类,TypeScript 类型系统也能够“理解”这种模式(构造函数等价于...f) { return fs.readFileSync(f); } P.S.实际上,TypeScript 对 CommonJS 模块的支持就是通过这种类型推断来完成的 命名空间推断 .js里,类、函数和对象字面量都视为命名空间
直到 2011 年,重构后的 JSDoc 3.0 已经可以运行在 Node.js 上 JSDoc 语法举例 定义对象类型: /** * @typedef {object} Rgb * @property..._clock = clock; } } 在实践中,多用于配合 jsdoc2md 等工具,自动生成库的 API 文档等。...但前面提到的 TS 的固有问题也困扰着开发者们,直到今年几起标志性事件的发生,将大家的目光拉回 JSDoc,人们惊讶地发现:JSDoc 并没有停留在旧时光中。...的类型声明定义成 TS 风格,更是支持了在 JSDoc 注释的类型声明中动态引入并解析 TS 类型的能力。...MyPojo * @property {Integer} [id] * @property {String} [name] */ 在转换的方法上,理论上如果能基于 AST 等手段当然更好,但如本例中的
函数多行注释 函数(方法)注释也是多行注释的一种,但是包含了特殊的注释要求,参照JSDoc。...以下字段并不是全部,全部请参考JSDoc中文文档或JSDoc中文文档 常用注释关键字 注释名 语法 含义 示例 @param @param 参数名 {参数类型} 描述信息 描述参数的信息 @param...return @return {返回类型} 描述信息 描述返回值的信息 @return {Boolean} true:可执行;false:不可执行 @author @author 作者信息 [附属信息:如邮箱...当函数为静态函数时,必须添加@static;当函数有参数时,必须使用@param;当函数有返回值时,必须使用@return。...小康的jsdoc
你可以使用它记录如:命名空间、类、方法、方法参数等。...docdash (example) tui-jsdoc-template (example) 构建工具 JSDoc Grunt plugin JSDoc Gulp plugin 其它工具 jsdoc-to-markdown...它可以将测试代码和用户手册一并集成到文档中,支持通过插件添加自定义功能。...有了它,只需在写源码的时候顺手写上一些简单的注释,就可以生成出漂亮的文档了。项目支持大部分主流语言,注释维护起来也比较方便,不需要额外再维护一份文档。...自己整理了一份2018最全面前端学习资料,从最基础的HTML+CSS+JS到移动端HTML5到各种框架都有整理,送给每一位前端小伙伴,有想学习web前端的,或是转行,或是大学生,还有工作中想提升自己能力的
5、jsdoc 地址:https://github.com/jsdoc/jsdoc ? 用于 JavaScript 的 API 文档生成器。...如果你需要记录你的个人功能,那么jsdoc是一个很好的工具。生成的文件非常基础,用于文档目的,你可以在短时间内拥有自己的功能文档。...该文档对于新开发人员来说也很棒且易于使用,并且在开始使用jsdoc时不需要太多经验。 特别是如果你在团队中工作,它会提高你工作流程的整体生产力,因为你已经定义了自己的功能。...以有限的并发运行多个 Promise 返回和异步函数。 如果你想限制 JavaScript 中的 promise 或同时阻止来自服务器的所有请求调用,那么这个库适合你。...这个库使代码在处理 cookie 时更加清晰和可用,你可以使用一个简单的 API 来管理 cookie,其中包括开发人员需要的一切。
而这种情况下我们可以很简单的使用 JSDoc 来手动描述这个函数的作用: ?...,查看到前两个函数所返回对象的部分属性, 但是仍然不能知道这些属性的类型是什么。...基础用法 如上文所说的,JSDoc 是写在注释中的一些特定格式内容。...而多行的写法是比较常用的,在 vscode 中可以直接在函数上方键入 /** 然后回车,编辑器会自动填充很多的内容,包括参数类型、参数描述以及函数描述的预留位置,使用TAB键即可快速切换。 ?...关于函数参数,在 JSDoc 中两种方式可以描述复杂类型: ?
jsdoc - API文档生成器,类似于JavaDoc或PHPDoc。 5.日志工具 5.1 应用场景1:如何实现日志分类?...6.3 应用场景3: 如何在命令行中显示进度条? ? 可以使用以下工具: progress - Node.js的灵活ascii进度条。...progress-estimator - 记录进度条并估计完成承诺所需的时间。 6.4 应用场景4: 如何在命令行执行多任务? ? 可以使用以下工具: listr - 命令行任务列表。...qrcode-terminal - 命令行中显示二维码。 treeify - 将javascript对象漂亮地打印为树。...joi - 基于JavaScript对象的对象模式描述语言和验证器。 async-validator - 异步校验。
好消息是,JSDoc 的 @ts-check,可以现实这个愿望。...JSDoc 类型标记 既然ts-check这么好用,我们来看看 JSDoc 类型的注释支持哪些类型的检测。.../** * - string类型 * @type {string} */ let a1; /** * - windows对象类型 * @type {Window} */ let a2...} */ var nds; /** @type {Array} */ var nas; // ---- 还可以指定对象字面量类型。...写在最后 对于老项目,使用 // @ts-check 和 JSDoc 来来享受TypeScript类型系统的好处是最简单、学习成本最低的方法。
你可以通过使用JSDoc在JavaScript中获得TypeScript的所有好处 TypeScript所提供的是一个静态类型系统。这意味着类型信息在运行代码中没有影响。...JSDoc 在JavaScript诞生25年多后,JSDoc作为一种注释JavaScript代码的方式被引入。它是一种正式的标记语言,允许IDE在开发者看到一个函数时提供额外的上下文。...最重要的是你要知道,几乎所有你能在.ts文件中做的事情,你都能用JSDoc来做。...但这里有几个例子: 带有原生类型的函数参数: /** * @param {string} a * @param {number} b */ function foo(a, b) {} 使用TypeScript...* @param {Window} window */ function foo(element, window) {} /** @type {number[]} */ let years 定义对象字面量和函数
//时间戳日期格式化函数 function formTime(time,isyear){ } 亦或者是这样的?.../* 时间戳日期格式化函数 */ function formTime(time,isyear){ } 简单的变量声明之类的内容可以进行简单注释,但是函数就不能这样做了,要知道注释的作用是一种为了让代码更易读...、易维护、易理解,起到提示的作用的,上面的两个注释都是正确的,但是它起到的作用太低了,在正式工作中我们往往会协同开发,这种注释是万万不可的。...自动化生成文档 既然叫文档注释,那么生成个文档也没什么好奇怪的吧, 生成文档的包有很多种,比如jsDoc,apiDoc等等,在这里我使用jsdoc。 安装 输入以下命令进行全局安装。...npm install jsdoc -g 基本使用 jsdoc 文件名 其他的使用方式可以去官网查看 jsdoc 33.js 执行完此命令,会生成一个out文件夹,查看里面的index页面即可,右边侧边栏会显示函数的使用
原型链写法 要开始编写插件就得先了解JS模块化,早期的模块化是利用了函数自执行来实现的,在单独的函数作用域中执行代码可以避免插件中定义的变量污染到全局变量,举个栗子,以下代码实现了一个简单随机数生成的插件...Fn下的原型对象。...补充:模块化的发展 早期利用函数自执行实现,在单独的函数作用域中执行代码(如 JQuery ) AMD:引入 require.js 编写模块化,引用依赖必须提前声明 CMD:引入 sea.js 编写模块化...所以这里我们使用 JSDoc 来创建 API文档,它使用简单,只需要在代码中编写规范的注释,即能根据注释自动生成文档,一举多得,十分优雅!...* @param {Array} arr * @param {String} 对象中相同的关键字(如id) * @return {Array} 返回新数组,eg: ArrayDelSome([{
领取专属 10元无门槛券
手把手带您无忧上云