摘要:融合思路解決這個問題,有兩種思路。給我們帶來了以下新成員模塊服務指令篩選器和控制器。與其他類是通過類的名稱區分的,名稱統一以結尾。這種處理方式是一種折中方案,如果想要更加規范優雅的話,建議使用自定義標簽來解決。
字數:1568
閱讀時間:10分鐘
??前面,我們以一個實戰案例來詳細說明了如何在實際開發中使用JSDuck工具。但是,并不是所有的時候,代碼的封裝方式都受我們控制的。例如,如果我們使用了現在的幾個主流框架AngularJS、React或者Vue的時候,代碼的封裝方式就必須按照框架定義的方式來構建。當我們的代碼中出現了模塊、控制器、服務、指令等JSDuck完全不認識的組成部分時,我們該如何使用JSDuck來正確描述我們的代碼呢?
??那么,下面,筆者就以 AngularJS 為例,來說一說筆者自己的解決方案。
??解決這個問題,有兩種思路。第一種,可以將JSDuck不識別的代碼部分映射到工具識別的標簽來進行描述。第二種,既然沒有現成的標簽來描述這些新成員,那我們可以自定義一套標簽來描述它們。
??第一種方法更方便,不需要額外編碼;第二種方法更優雅,但是需要自定義一整套標簽。
??這里,由于筆者對文檔的要求主要是實用,不需要那么完美,而且現在也沒有過多的精力來研發一整套標簽。所以,筆者選擇了第一種解決方案。
??第一種方案最核心的地方就是需要確定AngularJS框架給我們的代碼帶來了哪些新成員,而后如何將這些新成員映射到原有的標簽中去。
??AngularJS給我們帶來了以下新成員:模塊、服務、指令、篩選器和控制器。然后映射關系如下:
新成員 | 映射的JSDuck標簽 |
---|---|
模塊 | 模塊類(@class) |
服務 | 服務類(@class) |
指令 | 模塊類中的函數(@method) |
篩選器 | 模塊類中的函數(@method) |
控制器 | 控制器類(@class) |
??其中,模塊是一個特殊的類,我叫它模塊類,它和其他的類是通過命名空間和類名來區分的。例如,NgModule.layout ,就是我的一個模塊類,NgModule 這個命名空間就是專門存放模塊類的命名空間。
??服務是另一種特殊的類,我叫它服務類,服務類和模塊類是通過命名空間來關聯的,并且服務類的名稱比較特殊,統一以 “$” 符號開頭。例如 , NgModule.layout.$layoutTag 就是我的一個服務類,它的命名空間就是它所屬的模塊類。
??指令和篩選器就比較簡單了,他們都是所屬模塊類中的函數。
??控制器也是一個特殊的類,我叫他控制器類,它的命名空間是它所屬模塊類。與其他類是通過類的名稱區分的,名稱統一以”Ctrl“結尾。例如:NgModule.frame3.frameCtrl 就是我的一個控制器類。這里,父子控制器就直接通過父類子類來表示。
??整體的思路就是如此,那么,下面咱還是直接上代碼來說話吧!
??如下所示,就是我們的一個模塊類的部分代碼(為了方便查看,只留下了注釋,刪掉了具體實現):
/** * 頁面通用小控件模塊 * @class NgModule.layout * @alias gm.ngCustom.layout * @author lsjcoder */ angular.module("gm.ngCustom.layout",[]).provider("$layoutTag", /** * 表示查詢項的標簽的服務 * @class NgModule.layout.$layoutTag * @alias $layoutTag * @author lsjcoder */ function() { this.$get = [function () { function factory() { var $layout = {}; /** * @member NgModule.layout.$layoutTag * @method getCheckedTags 獲取選中的標簽 * @param {Array} tags 標簽集合 * @returns {Array} 選中的標簽集合 */ $layout.getCheckedTags = function(tags){ }; /** * @member NgModule.layout.$layoutTag * @method clearCheck 清空選擇 * @param {Array} tags 標簽集合 */ $layout.clearCheck = function(tags){ }; return $layout; } return factory; }]; }).directive("gmTags",["$layoutTag", /** * @member NgModule.layout * @method gmTags 標簽指令,EAC模式 * @param {Number} [max-tag-num] DOM屬性傳值,外部顯示出來的標簽最大個數,默認會自動根據頁面寬度計算 * @param {Boolean} [multi = true] DOM屬性傳值,是否開啟多選模式 * @param {Object} tagdata 作用于傳值,指令配置項 * @param {String} tagdata.checkTag 選中標簽后調用函數的名稱 * @param {Array} tagdata.tags 標簽數據 */ function($layoutTag){ //查詢表單中標簽指令 return { restrict: "ECA", templateUrl: "tag.tpl.html", replace: true, scope: { tagdata: "=" }, link: function (scope, element, attr, transclution) { } } }]).directive("dateChoose", /** * @member NgModule.layout * @method dateChoose 日期指令,EAC模式 */ function(){ return { restrict:"EAC", link :function(scope,element,attr,transclution){ } } }).directive("timeChoose", /** * @member NgModule.layout * @method timeChoose 時間指令,EAC模式 */ function(){ return { restrict:"EAC", link :function(scope,element,attr,transclution){ } } });
??代碼上看已經很清晰了,這段代碼包含了模塊以及模塊中服務和指令的注釋方式。篩選器同指令,就不做贅述了。
??下面,我們再看看控制器的注釋方式:
/** * @class NgModule.frame3 frame3模塊 * @alias frame3 * @author lsjcoder */ var frameApp = angular.module("frameApp",[]); /** * @class NgModule.frame3.frameCtrl 框架控制器 * @extends NgModule.frame.frameCtrl * @author lsjcoder */ frameApp.controller("frameCtrl",["$scope",function($scope){ /** * @member NgModule.frame3.frameCtrl * @method refreshPage 刷新路由頁面 * @param {String} strPath 路由地址 * @author lsjcoder */ $scope.refreshPage = function(strPath){ }; }]);
??如上代碼所示,我聲明了一個控制器 NgModule.frame3.frameCtrl ,它屬于模塊 NgModule.frame3 ,父控制器是 NgModule.frame.frameCtrl ,內部有一個函數成員 refreshPage 。
??至此,我們就可以按照這種方式來描述所有因為使用 AngularJS 框架而新增的代碼部分了。其他的框架也可以使用相同的辦法來處理。這種處理方式是一種折中方案,如果想要更加規范、優雅的話,建議使用自定義標簽來解決。
??歡迎大伙關注我的微信公眾號,和老司機一起擼代碼:
文章版權歸作者所有,未經允許請勿轉載,若此文章存在違規行為,您可以聯系管理員刪除。
轉載請注明本文地址:http://specialneedsforspecialkids.com/yun/90721.html
摘要:本文比較了種較為主流的注釋文檔生成工具。應該說是非常適合開源項目多個作者共同維護的一個文檔工具。最后我選擇了作為文檔生成的工具。為了支持多種語言,它僅對注釋塊內部的內容進行解析。 最近隨著寫Node以及獨立的CommonJS模塊越來越多,我發現有一份好的文檔不僅可以幫助自己在應用這些接口的時候不至于迷糊,而且對于共同開發的情況下,能夠省去大量團隊的交流和Debug的時間。 本文比較了...
摘要:我們在對現在較主流的五個文檔工具分別作了調研和嘗試,得到結論如下工具優點缺點提供了完整的模板開發事件觸發等接口,使用非常靈活。至此,的環境部署已經全部完成了。 字數:981 閱讀時間:5分鐘 選型依據 ? 在經歷了數個上線的項目之后,筆者所在的團隊已經沉淀了一個相對穩定版本的前端框架。因此,我們需要出具一套框架API文檔,以便公司其他成員的使用和框架的后期維護。我們在對...
摘要:語法父類名表示當前類繼承于哪個類的標簽。成員標簽成員標簽作用于類中的配置屬性函數事件。表明可被子類繼承,和一起使用。示例獲取圓的面積圓的半徑面積值作用于函數,表明函數的標簽。作用于函數,表明構造函數參數的標簽,用法同。 字數:3692字 閱讀時間:15分鐘 前言 ? 首先,咱們有一個前提,JSDuck對我們而言只是一個便于API查看的文檔化工具。因此,只要它能夠滿足我們文...
閱讀 638·2021-11-25 09:43
閱讀 1906·2021-11-17 09:33
閱讀 824·2021-09-07 09:58
閱讀 2062·2021-08-16 10:52
閱讀 482·2019-08-30 15:52
閱讀 1722·2019-08-30 15:43
閱讀 971·2019-08-30 15:43
閱讀 2922·2019-08-29 16:41