vue 插入word模板 项目_10 分钟为你的 vue 项目编写代码文档

代码文档是软件开发使用和维护的必备资料,有了文档,开发和维护以及协作的效率将变得大大提升。tips:如果对 JSDoc 已经熟悉,可以直接跳到实战演练环节。

什么是文档?软件文档或者源代码文档是指与软件系统及其软件工程过程有关联的文本实体。文档的类型包括软件需求文档,设计文档,测试文档,用户手册等。

其中的代码文档一般是在软件开发过程中由开发者写就的,而用户手册等非过程类文档是由专门的非技术类写作人员写就的。 文档能提高软件开发的效率,保证软件的质量,而且在软件的使用过程中有指导、帮助、解惑的作用,尤其在维护工作中,文档是不可或缺的资料。

因此建立文档很有必要,对于前端从业者,我们可能更加熟悉接口文档,那有没有想过为自己的项目添加代码文档呢?特别是针对 vue项目,在没有Composition API 的情况下,可能同一功能的逻辑散落在.vue 文件的各个部分,使协作和维护变得困难和效率低下,特别是在那些没有 TypeScript 以及 Vue3 加持下的项目。因此今天我们就说一下,如何为你的 Vue项目编写代码文档。

如何写代码文档?

针对 JavaScript 项目添加文档,目前当下比较流行的方法使用 JSDoc 生成文档,按照 JSDoc 的标注在源代码中添加注释,使用 JSDoc 就能自动生成对应的文档.针对 Vue 项目,JSDoc 是不认识.vue 单文件的,因此还需要使用一款基于 JSDoc 的插件——jsdoc-vue 来生成。下面,让我们先分别来认识这两个工具。

JSDoc是JavaScript的API文档生成器,类似于Javadoc或phpDocumentor。您可以将代码注释直接添加到源代码中,并紧随代码本身。JSDoc工具将扫描您的源代码并为您生成一个HTML文档网站。

它的使用姿势大概就是这样去编写一个函数的文档:

/*** @description 渲染每一行的样式,阶段进行中高亮,反之则不高亮* @param { object } row 每一行的数据* @returns {string} ("ing-row"|"other-row"|"start-row")*/

rowClass( row ) {

// 没有结束的独立阶段置为高亮 if (row.preStageId?.length === 0 && row.statue === 0) {

return "start-row";

} else if (row.statue === 1) {

// 进行中的高亮 return "ing-row";

}

// 其他的灰色 return "other-row";

},

这样注释之后,该部分最后得的文档是这样

生成的文档能够相应的标注出你的参数类型以及释义,以及该函数功能说明,以及返回参数说明。总之,就是对应输出你注释的内容,更多详细用法请看官方文档。下面着重说下如何使用 JSDoc针对 Vue 项目的插件jsdoc-vue.jsdoc-vue使用姿势一览​github.com

A JSDoc plugin for listing props, data, computed data, and methods from *.vue files.

翻译过来就是一个可以将.vue 文件中 props,data,computed,methods 这几个属性列出来的 JSDoc插件。

该插件的也很简单,就只是提供了四个语法 - @vue-prop (对应props) - @vue-data (对应data) - @vue-computed (对应 computed) - @vue-event (对应组件监听事件)

使用示例

/*** @vue-prop {Number} initialCounter - Initial counter's value* @vue-prop {Number} [step=1] - Step* @vue-data {Number} counter - Current counter's value* @vue-computed {String} message* @vue-event {Number} increment - Emit counter's value after increment* @vue-event {Number} decrement - Emit counter's value after decrement*/

除了特定的前缀不一样,使用方法和语法都是一样的。在配置好之后(稍后会讲如何配置),你可以这样在.vue 中编写 vue 组件的文档

/*** 顶部选择当前大赛的组件* @vue-data { Boolean } firstEnter - 是否首次进入系统的标志,以本地缓存为准* @vue-computed { Object } currentRace - 系统当前选择的大赛* @vue-watch { Object } raceList - 大赛列表改变时,重新选择当前大赛,以防当前大赛被删除时,当前组件数据未更新* @vue-event { Void } handleDefaultRace - 选择当前的大赛的默认逻辑* @vue-event { Number } isFirstEnter - 判断是否是首次进入的逻辑* @vue-event { Boolean } competitionChange - 当用户主动切换大赛时触发的具体逻辑* @vue-event { Void } handleCommand - 当用户主动切换大赛时触发的中转时间*/

对应的文档会生成如下样式:

tips:.vue中的方法只需要注释在方法顶部就可,会自动同步文档到 methods 这一栏去。

上面已经介绍了这两个工具的基本使用,下面让我们具体来操作一下吧。

实战演练安装依赖

# 安装jsdoc jsdoc-vue

npm install --save-dev jsdoc jsdoc-vuejs

# vue 版本需要和 vue-tempate-compiler 版本一致,不然会报错,重要!

# 如果你使用 vue 的版本 2.5.21,请安装 vue-template-compiler 对应版本

npm install --save-dev vue-template-compiler@2.5.21

# jsdoc 默认生成的和网站样式很简单,这里我们下载一个网站的html 模版

npm i -D tui-jsdoc-template2.编写配置

下载安装完毕,因为使用了插件,所以需要去配置我们的配置文件,详情参考如何配置 JSDoc 的配置文件​jsdoc.app

在项目根目录下新建一个 vuedoc.config.json

{

"plugins": ["node_modules/jsdoc-vuejs"], // 配置插件

"source": {

"includePattern": "\\.(vue|js)$" // 需要编译的文件,正则只包含.vue 和.js 文件

},

"opts": {

"template": "node_modules/tui-jsdoc-template" // 我们生成网站使用的模版

},

"templates": { // logo配置

"logo": {

"url": "http://img.pinxianhs.com/logo/logo.png",

"width": "30px",

"height": "30px",

"link": "https://github.com/nhnent/tui.jsdoc-template"

},

"name": "全国大学生工业设计大赛后台管理系统代码说明文档", // 网站顶部名称

"footerText": "全国大学生工业设计大赛后台管理系统",

"useCollapsibles": true,

"tabNames": {

"api": "API",

"tutorials": "Examples"

},

// 修改默认样式

"default": {

"staticFiles": {

"include": ["src/"]

}

},

"css": ["styles/doc.css"]

}

}3.添加注释

在.vue 文档中添加注释

.vue 部分

.methods 部分

4.生成网站,然后运行命令

jsdoc ./src -c ./vuedoc.config.json -r./src 要编译的目录

-c后面接的是配置文件名

-r代表递归编译子目录,默认最大层级 10

更多配置查看 JSDoc 使用方法。

编译之后,项目根目录下会多一个 out 文件夹,如图所示

我们再安装一个 http-server,将这个文档项目跑起来,安装依赖

npm i --save-dev http-server

以out 文件夹为根目录,在 http-server 里面跑起这个应用,要做的就是在 npm scripts 里面添加两条

"scripts": {

"serve:doc": "http-server ./out -p 3001 -o" //自动在浏览器打开文档网站,端口 3001 "doc": "jsdoc ./src -c ./vuedoc.config.json -r && npm run serve:doc", // 编译并自动打开文档网站 }

然后我们运行 npm run doc就能打开我们的vue 文档网站了。

运行界面

网站页面

logo以及顶部应用名称都可以自己配置,在样式方面,也可以自己在配置文件中覆盖。 左侧针对 es6 语法的 export 导出的文件都会自动被归类到 modules,顶层函数划分到 global 里面去,若有相应 class 也会自动归类。

值得一提的是,可以在这里进行全局搜索,可以快速 debug 和熟悉项目。

另外也可以进行代码溯源。

点击图片红框位置,可以快速看到源码,是不是太方便了。 赶快 get 吧。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/306442.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

python小游戏——21点

编写一副扑克牌和一个发牌函数,要求: (1) 创建一副扑克牌,不包含两个Joker,其它牌面每个四张,花色可以用任意特殊符号表示; (2) 按照21点的游戏规则,使用学过的数据类型来指定每张牌的点数,其中数字牌的点数与同数字大小,J、Q和K的点数为0.5,A的点数为1; (3) 发牌函…

Magicodes.IE 2.5版本发布

今天我们发布了2.5版本,这当然也离不开大家对Magicodes.IE的支持,今天我也是跟往常一样列举了该版本一些重要的更新内容。当然也要说一下,在这个版本中我们设计了全新的LOGO。Excel导出Excel导出支持HeaderRowIndex #164(https://…

算法题目——最短路径问题(HDU—1007)

题目链接:HDU-1007 前序: 先看一维中的最短路径的计算方式 问题的简单描述:(题意) 在一个笛卡尔系中,n个点分布不一,在这N个点中,求出相距最短的两个点之间的距离 思路: 分治二分法 解题报告…

没有Kubernets,学习Docker还有用吗?

Docker容器化和Kubernetes容器编排,作为微服务和云原生的核心依赖,这几年已是大红大紫全民皆知。然而近日Kubernetes官方发布公告,宣布自 v1.20 起放弃对 Docker 的支持,惊呆了一众开发者。在这背后,究竟是人性的扭曲&…

oracle 查看函数被哪些触发器引用_oracle如何查看存储过程,存储函数,触发器的具体内容...

(1)set serveroutput on实现plsql developer 打印输出(2)如何查看存储过程,存储函数,触发器的内容查 user_sources表eg:查询GET_DEPT_SUMSAL这个存储函数的内容SQL> desc user_source名称 是否为空? 类型-------------------------------…

算法题目——二次函数三分求极值(HDU-3714)

题目链接:HDU-3714 题目描述: 对于N个二次函数,求每个二次函数的最小值中的最大值 思路: 使用三分法求极值(递归调用) 对于这种在指定区间里只有一个极值点的函数(凸函数凹函数都可以&#xff…

怎样才能去掉图片锁定纵横比_1分钟批量统一Word中300张图片的大小!无需插件、代码,超级简单...

很多时候我们需要将在Word中插入很多张图片,插入完成之后,一般我们还要统一它们的大小,如果是少量的图片的话,我们可以一个一个选择,然后再进行设置。或者先设置好一张图片后,再通过【F4】键,进…

我国火力发电站的大脑用上了国产系统

近年来,我国核电、水电、风电、光伏产业发展迅速,但从发电总量来看,火电依然占据7成以上的发电比例。水电、风电、光伏等清洁能源受自然条件限制,只能成为火电的有效补充,而不可能取代火电。而福岛核事故、切尔诺贝利核…

require 动态加载_require,exports,module.exports和import,export,export default

我们前端在开发过程中经常会遇到导入导出功能,在导入时,有时候是require,有时候是import在导出时,有时候是exports,module.exports,有时候是export,export default今天我们对这些内容进行简单的…

Newbe.ObjectVisitor 0.4.4 发布,模型验证器上线

Newbe.Claptrap 0.4.4 发布,模型验证器上线。更新内容完全基于表达式树的模型验证器本版本,我们带来了基于表达式树实现的模型验证器。并实现了很多内置的验证方法。我们罗列了与 FluentValidation 比较的情况:Build in ValidatorsFluentVali…

算法题目中经典问题(易错点)

算法题目中经典问题.易错点 (一).二维数组的传参问题1.方法一:形参为二维数组并给定第二维长度2.方法二:形参为指向数组的指针并给出数组长度3.二维数组定义为全局变量(二).多组测试控制台数据,输入到文件结束(三).进制转换中的小问题1.使用字符串来存储,每一位(四).结构体…

dotnet core 应用是如何跑起来的 通过AppHost理解运行过程

在 dotnet 的输出路径里面,可以看到有一个有趣的可执行文件,这个可执行文件是如何在框架发布和独立发布的时候,找到 dotnet 程序的运行时的,这个可执行文件里面包含了哪些内容在回答上面的问题之前,请大家尝试打开 C:\…

算法题目——整数划分(HRBUST-2004)

题目链接:HRBUST-2004 递归法: 1.当n1时,此时只有1种解{1}; 2.当m1时,此时也只有1种解{1,1,1, … 3.当n> m时,要分为最大数包含m和不包含m两种情况。 ●包含m:此时就是{mx1,2…}. 其中x1x23.… n-m, 就相当于求和为n-m,最…

dotnet core 应用是如何跑起来的 通过自己写一个 dotnet host 理解运行过程

在上一篇博客是使用官方提供的 AppHost 跑起来整个 dotnet 程序。本文告诉大家在 dotnet 程序运行到托管代码之前,所需要的 Native 部分的逻辑。包括如何寻找 dotnet 运行时,如何加载运行时和框架然后跑起来业务端的 dll 文件的逻辑在上一篇博客告诉大家…

android虚线边框_Android实现代码画虚线边框背景效果

实现如下边框效果:虚线画效果,可以使用Android中的xml来做。下面话不多说,直接上代码:android:id"id/coupon_popup"android:layout_width"320dp"android:layout_height"200dp"android:layout_margi…

算法题目——多米诺骨牌问题(POJ-2663)

题目链接:POJ-2663 设有形状一样的多米诺牌,每张牌恰好覆盖棋盘上相邻的两个方格,即一张多米诺牌是一张 1 行 2 列或者 2 行 1 列的牌。那么,是否能够把 32 张多米诺牌摆放到棋盘上,使得任何两张多米诺牌均不重叠&…

【招聘(上海)】 坚果云 招聘Windows客户端(WPF方向)

岗位职责:1、负责坚果云在Windows 10平台上WPF应用的开发与维护;2、负责基于WPF的Windows平台核心客户端产品开发,维护与测试;3、WPF桌面应用将具备丰富的文件展示和文件管理功能,其中与操作系统交互, 复杂…

三相全桥整流电路_三相桥式全控整流电路

收稿日期:2002-04-12作者简介:陈强(1976—),男,硕士研究生1三相桥式全控整流及单相交流调压实验装置的研制陈强,杨旭,王兆安(西安交通大学电气工程学院,西安710049)摘要:本文结合具体的三相全控整流电路的研制,介绍了以国产集成芯片KJ004和KJ041为中心的触发电路的工作过程及主…

算法题目——Problem A 二进制(北邮机试)

Problem A 二进制 题目描述 32位二进制数 X ,对其进行X+1,X+3操作,并输出。注意不能忽略前导0。 输入 第一行,一个整数 T ,代表测试数据组数。接着 T 行,输入32为二进制数输出对每组测试数据。 输出 两行,第一行为X+1,第二行为X+3. 测试样例 输入 2 00000000000000000000…

merge函数_c语言中的merge函数

展开全部merge()是C标准库的函数,主要实现函数的排序和合并,不仅仅是合并,具体要求参e5a48de588b63231313335323631343130323136353331333431373261照标准库。#include"stdafx.h"#include#include#include#includeusingnamespacest…