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 吧。
總結
以上是生活随笔為你收集整理的vue 插入word模板 项目_10 分钟为你的 vue 项目编写代码文档的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： oracle symonym_Oracl
- 下一篇： react全局状态管理_rxv: 在Re