糯麦 NurMai

400-158-5662

糯麦科技

/

新闻资讯

/

技术讨论

/

JSDoc 可替代 TypeScript 的方案?

JSDoc 可替代 TypeScript 的方案?

原创 新闻资讯

于 2023-11-30 10:15:35 发布

16840 浏览

许多开发者喜欢使用TypeScript,因为它的类型检查功能可以提供更好的代码提示、错误检查和自动补全。然而,这需要额外的转译步骤,可能会带来麻烦和浪费时间。本文将向您展示如何使用JSDoc来获得相同类型的控制,同时使用纯JavaScript进行最快的开发时间和更好的文档编写!


JavaScript已经巩固了其作为近年来最常用的编程语言之一的地位。它以在Web开发中编写的简易性和灵活性而闻名。随着技术的不断发展,JavaScript已经从最初只是一个简单的脚本语言,发展成为可以构建大型、复杂应用程序的强大语言。现在,JavaScript已经被广泛用于开发各种类型的应用程序,从小型脚本到完整的大型应用程序,它都展现出了强大的能力。


不幸的是,这揭示了语言的缺陷。其中一些包括:

•  缺乏静态类型和严格的类型检查:JavaScript非常宽容,允许将参数传递给不接受它的函数,可以省略必需的值等。这在静态类型语言中是不允许的,因为会在编译时出错。这些错误会在JavaScript应用程序中出现在生产环境中。

•  JavaScript在扩展和维护大型代码库方面存在困难:JavaScript没有提供强大的机制来管理大型代码库,这使得随着时间的推移,项目的扩展和维护变得具有挑战性。


Typescript


2014年,微软推出了TypeScript v1.0。这改变了整个JavaScript生态系统。


TypeScript是JavaScript的超集,解决了上述问题以及更多问题。这使得它在最近的时间里越来越受欢迎。


2022年的State of Js调查显示TypeScript的使用率上升。


1.jpg


TypeScript 在解决了许多问题的同时,也并非没有缺点。


在本文中,我们将介绍一种非常好的 TypeScript 替代方案,名为 JSDoc,它解决了静态类型和可扩展性的问题,同时也消除了 TypeScript 在 JavaScript 生态系统中的一些缺点。


JSDoc是什么?

JSDoc是一个用于JavaScript的文档系统。它通过使用包含JSDoc语法的注释来工作。


JSDoc语法具有多种用途,包括用类型注释值,为函数指定参数和返回类型,为函数提供文档和使用信息,以及类型错误等。类似于TypeScript,这些可以被代码编辑器利用,作为指导程序员构建、使用或维护所述代码库的指南。


JSDoc VS TypeScript

JSDoc和TypeScript都解决了编写和维护纯JavaScript代码的问题。然而,它们采用了不同的方法,各有利弊。


JSDoc相对于TypeScript的优势:

•  灵活性和兼容性:JSDoc只是JavaScript注释,这意味着它可以添加到任何JavaScript代码库中,而不受语言版本的限制,并且不像TypeScript那样与编译器绑定。

•  代码注释:JSDoc不仅可以用于类型检查,还可以用于添加更多的文档,描述函数的工作原理,并生成文档网站,从而提供价值以增强代码的可维护性和理解性。

•  无需编译步骤:这是从TypeScript转换到JSDoc最具动力的原因之一。TypeScript需要编译将TypeScript代码转换为JavaScript,以便浏览器能够理解,而JSDoc不需要任何其他步骤,因为它们只是“注释”,这是JavaScript本身支持的特性。与每次进行更改时都需要使用必要的TypeScript构建流程相比,这可以简化并加快开发工作流程。


使用JSDoc的缺点


虽然JSDoc相对于TypeScript有很多优势,但是随着时间的推移,TypeScript的使用越来越普遍。以下是TypeScript相对于JSDoc的一些优势:

•  更强大的静态类型:TypeScript提供了一种强大的类型模型,并在编译时捕获这些错误。与JSDoc不同,这些类型在代码本身中结束,并且不受强制执行。

•  类型推断:TypeScript 可以从其值推断类型。这有助于减少显式类型注解,使代码库更简洁。

•  转译:TypeScript 可以通过其 polyfill 功能采用 JavaScript 语言的最新和未来特性。它可以将这些代码有效地转译成可理解的版本,以适应尚未支持这些特性的浏览器。


如何使用JSDoc:基础知识


由于其长期存在,JSDoc在所有现代编辑器中都得到了广泛支持,并且可以直接使用,无需任何安装。


在一个 .js 文件中添加JSDoc,如所述只是注释,通过使用额外的 * 开启一个注释来完成

// Normal Javascript Comment 1
/* Normal Javascript Comment 2 */ 

/** 
 JSDoc containing two asterisks
  */

这些是一些入门的基本功能。


向代码块添加代码描述:

/** The name of the language JSDoc is written for*/
const language = "JavaScript"

为值添加类型:

/** 
 * This represents the writer of this blog
 * @type {string}
 */
const writerName = "Elijah"

现在,指定用户名变量应为字符串类型。


向对象和数组添加类型:

/** 
* @type {Array<string>}
*/
const colours = ['red', 'blue', 'green']

/**
 * @type {number[]}
 */
const primeNumbers = [1, 2, 3, 5, 7]

两种方法在JSDoc中都是有效的(与Typescript相同)。


通过使用 @typedef 指令可以创建一个对象类型。

/**
 * * @typedef {Object} User - A user schema 
 * @property {number} id 
 * @property {string} username
 * @property {string} email
 * @property {Array<number>} postLikes
 * @property {string[]} friends
 */
/**@type {User} */
const person1 = {
  id: 847,
  username: "Elijah",
  email: "elijah@user.com",
  postLikes: [44, 22, 24, 39],
  friends: ['fede', 'Elijah']
}
/** @type {User} */
const person2 = {
id: 424,
username: "Winston",
email: "winston@user.com",
postLike: [18, 53, 98],
friends: ['Favour', 'Jane']
}

输入函数(参数、返回值和预期错误类型):

/**
 * Divide two numbers.
 * @param {number} dividend - The number to be divided.
 * @param {number} divisor - The number to divide by.
 * @returns {number} The result of the division.
 */
function divideNumbers(dividend, divisor) {
    return dividend/divisor;
}

关键字 @param 后面定义一个类型,表示定义的函数将接受的值。你也可以在连字符(-)后面加上参数的描述。


关键字 @returns 用于定义函数返回的内容。这对于大型函数特别有用。可能很难浏览所有的代码,包括早期返回,以确定函数的预期行为。


此外,您可以使用 @throws 指令添加函数可能抛出的错误。


改进除法函数,我们可以指定如果除数为零则返回错误,并在代码中处理这种情况。

/**
 * Divide two numbers.
 * @param {number} dividend - The number to be divided.
 * @param {number} divisor - The number to divide by.
 * @returns {number} The result of the division.
 * @throws {ZeroDivisionError} Argument divisor must be non-zero
 */
function divideNumbers(dividend, divisor) {
    if (divisor === 0) {
        throw new DivisionByZeroError('Cannot Divide by zero')
    }
    return dividend/divisor;
}

@throws 可以接受错误类型(ZeroDivisionError)或描述(参数除数必须…)或两者皆有。

/**
 * Custom error for division by zero.
 */
class DivisionByZeroError extends Error {
    constructor(message = "Cannot Divide By Zero") {
        super(message);
      this.name = "DivisionByZeroError";
    }
}

由于JavaScript本身不会强制你处理错误,因此你必须这样做,因为它有助于提高协作和维护。


输入完整的类(描述、构造函数和方法)


更进一步,您还可以使用JSDoc输入完整的类语法。

/**
 * A Rectangle Class
 * @class
 * @classdec A four-sided polygon with opposite sides of equal length and four right angles
 */
class Rectangle {
  /**
   * Initializing a Rectangle object.
   * @param {number} length - The length of the rectangle.
   * @param {number} width - The width of the rectangle.
   */
  constructor(length, width) {
    this.length = length;
    this.width = width;
  }

  /**
   * Calculate the area of the rectangle.
   * @returns {number} The area of the rectangle.
   */
  calculateArea() {
    return this.length * this.width;
  }

  /**
   * Calculate the perimeter of the rectangle.
   * @returns {number} The perimeter of the rectangle.
   */
  calculatePerimeter() {
    return 2 * (this.length + this.width);
  }
}

上面是一个简单的矩形类,有两个方法来计算它的面积和周长。


@class 关键字用于表示需要使用 new 关键字调用的函数。 @classdec 用于描述整个类。在编写类时,通过添加类型和描述来进一步完善是很重要的。


•  构造函数

•  类中创建的所有方法和变量


我们使用 @params 关键字来提供需要传递给构造函数的参数的类型和描述。类中的方法与函数的类型方式相同,这在前一节中已经介绍过。


改进通用代码文档:


除了在代码中添加必要的类型之外,JSDoc还有很多方法可以提高可读性和理解的便利性。以下是其中的几个:


添加代码作者:可以使用 @author 指令添加项目的作者,包括作者的姓名和电子邮件

 /**
     * Possible title for this article
    * @type {string} 
    * @author Elijah [elijah@example.com]
    */
const articleTitle =  "Demystifying JSDoc"

你还可以添加代码片段,展示特定代码块的使用方法。这对于复杂的代码块尤其有用。

/** 
 * Sums of the square of two numbers a**2 + b**2
 * @example <caption>How to use the sumSquares function</caption>
 * // returns 13 
 * sumSquares(2, 3)
 * @example
 * // returns 41
 * sumSquares(4, 5)
 * // Typing the function
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {Number} Returns the sum of the squares
 * */
const sumSquares = function(a, b){
    return a**2 + b**2
}

我们使用 @example 指令来实现这一点。这也可以用 caption 标签来加注。


版本控制:您还可以使用 @version 指令指定项目的版本。

/** 
 * @version 1.0.0
 * @type {number} 
 * */
const meaningOfLife = 42

有用的链接:通常,您可能希望将用户指向其他地方,以便他们可以获取有关代码的更多知识。这可以是一个GitHub存储库、一些教程、博客等。为了实现这一点,有两个指令可以帮助实现。 @link 和 @tutorial。

/** 
 * How to use the link tags
 * Also see the {@link https://jsdoc.app/tags-inline-link.html official docs} for more information
 * @tutorial getting-started
 * */
function myFunction (){
}

@link 标签将 official docs 渲染为指定链接的链接。它用于创建到指定URL的链接,而 @tutorial 标签用于将用户引导到生成的文档中的相对教程链接。


创建模块:在JSDoc中创建模块可以使用文件顶部的 @module 标签。这将使当前文件成为一个模块。模块将在生成的文档网站上的单独部分中进行分组。

// jsdoc.js
/** @module firstDoc */
//The rest of the code goes here


转换 JSDoc 文件


使用JSDoc的最大优点之一是能够将JSDoc文件转换为文档网站,甚至转换为Typescript,以便享受使用Typescript的好处,如在编译时捕获错误、与Typescript项目集成等。


从JSDoc文件生成文档网站


如上所述,按照以下步骤可以制作出更易读的图形用户界面:


安装 jsdoc

npm install -g jsdoc

运行 jsdoc 以获取目标文件

jsdoc path/to/file.js


2.jpg


这是默认生成的模板的样子,但你可以配置模板的外观。


从JSDoc生成.d.ts文件


在TypeScript中, .d.ts 文件代表包含所有 .ts 文件都可以访问的类型声明文件。您可以通过以下步骤从JSDoc代码生成这些文件:


在项目文件夹中安装 tsd-jsdoc

npm install tsd-jsdoc


生成 .d.ts 文件

对于一个单独的文件

jsdoc -t node_modules/tsd-jsdoc/dist -r our/jsdoc/file/path.js

对于多个文件

jsdoc -t node_modules/tsd-jsdoc/dist -r file1.js file2.js file3.js ...

对于整个文件夹

jsdoc -t node_modules/tsd-jsdoc/dist -r src

它将所有类型的文件合并成一个 out/types.d.ts 文件。


注意:这假设您已经从前一节安装了 jsdoc 。如果没有,请先安装它,然后再运行此步骤。


结论

到目前为止,我们已经学会了使用JSDoc的基础知识,以及从JSDoc代码生成类型和文档网站。JSDoc在以下情况下特别有用:当您的Typescript编译时间/构建步骤对生产力产生相反的影响时,以及在处理遗留代码库时。


Rich Harris(Svelte 和 SvelteKit 的创始人)将整个 Svelte 和 SvelteKit 仓库从 TypeScript 转移到了 JSDoc。TypeScript 也已经为许多 JSDoc 声明添加了支持(来源)。

网站建设

小程序开发

电商设计

阅读排行

  • 1. 几行代码就能实现Html大转盘抽奖

    大转盘抽奖是网络互动营销的一种常见形式,其通过简单易懂的界面设计,让用户在游戏中体验到乐趣,同时也能增加商家与用户之间的互动。本文将详细介绍如何使用HTML,CSS和JavaScript来实现大转盘抽奖的功能。

    查看详情
  • 2. 浙江省同区域公司地址变更详细流程

    提前准备好所有需要的资料,包含:房屋租赁合同、房产证、营业执照正副本、代理人身份证正反面、承诺书(由于我们公司其中一区域已有注册另外一公司,所以必须需要承诺书)

    查看详情
  • 3. 微信支付商户申请接入流程

    微信支付,是微信向有出售物品/提供服务需求的商家提供推广销售、支付收款、经营分析的整套解决方案,包括多种支付方式,如JSAPI支付、小程序支付、APP支付H5支付等支付方式接入。

    查看详情
  • 4. 阿里云域名ICP网络备案流程

    根据《互联网信息服务管理办法》以及《非经营性互联网信息服务备案管理办法》,国家对非经营性互联网信息服务实行备案制度,对经营性互联网信息服务实行许可制度。

    查看详情
  • 5. 微信小程序申请注册流程

    微信小程序注册流程与微信公众号较为相似,同时微信小程序支持通过已认证的微信公众号进行注册申请,无需进行单独认证即可使用,同一个已认证微信公众号可同时绑定注册多个小程序。

    查看详情