JSDuck 與 AngularJS 融合技巧

前言

前面，我們以乙個實戰案例來詳細說明了如何在實際開發中使用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() ;
 /**
* @member ngmodule.layout.$layouttag
* @method getcheckedtags 獲取選中的標籤
* @param tags 標籤集合
* @returns 選中的標籤集合
*/ $layout.getcheckedtags = function(tags);
 /**
* @member ngmodule.layout.$layouttag
* @method clearcheck 清空選擇
* @param tags 標籤集合
*/ $layout.clearcheck = function(tags);
return $layout;
} return factory;
}];}).directive("gmtags",["$layouttag",
/*** @member ngmodule.layout
* @method gmtags 標籤指令，eac模式
* @param [max-tag-num] dom屬性傳值，外部顯示出來的標籤最大個數，缺省會自動根據頁面寬度計算
* @param [multi = true] dom屬性傳值，是否開啟多選模式
* @param tagdata 作用於傳值，指令配置項
* @param tagdata.checktag 選中標籤後呼叫函式的名稱
* @param tagdata.tags 標籤資料
*/ function($layouttag),
link: function (scope, element, attr, transclution) 
} }]).directive("datechoose",
/*** @member ngmodule.layout
* @method datechoose 日期指令，eac模式
*/ function()
} }).directive("timechoose",
/*** @member ngmodule.layout
* @method timechoose 時間指令，eac模式
*/ function()
} });

**上看已經很清晰了，這段**包含了模組以及模組中服務和指令的注釋方式。篩選器同指令，就不做贅述了。

下面，我們再看看控制器的注釋方式：

/**
* @class ngmodule.frame3 frame3模組
* @alias frame3
* @author lsjcoder
*//**
* @class ngmodule.frame3.framectrl 框架控制器
* @extends ngmodule.frame.framectrl
* @author lsjcoder
*/ /**
* @member ngmodule.frame3.framectrl
* @method refreshpage 重新整理路由頁面
* @param strpath 路由位址
* @author lsjcoder
*/ $scope.refreshpage = function(strpath);
}]);

如上**所示，我宣告了乙個控制器 ngmodule.frame3.framectrl ，它屬於模組 ngmodule.frame3 ，父控制器是 ngmodule.frame.framectrl ，內部有乙個函式成員 refreshpage 。

至此，我們就可以按照這種方式來描述所有因為使用 angularjs 框架而新增的**部分了。其他的框架也可以使用相同的辦法來處理。這種處理方式是一種折中方案，如果想要更加規範、優雅的話，建議使用自定義標籤來解決。

JSDuck 與 AngularJS 融合技巧

JSDuck 與 AngularJS 融合技巧

以應用為目的從零開始學習AngularJS

五分鐘玩轉文件化工具JSDuck

JSDuck 與 AngularJS 融合技巧

JSDuck 與 AngularJS 融合技巧

以應用為目的從零開始學習AngularJS

五分鐘玩轉文件化工具JSDuck

相關推薦