前言
前面，我们以一个实战案例来详细说明了如何在实际开发中使用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 框架而新增的代码部分了。其他的框架也可以使用相同的办法来处理。这种处理方式是一种折中方案，如果想要更加规范、优雅的话，建议使用自定义标签来解决。
原文发布时间：2017/12/26
原文作者：老司机带你撸代码
本文来源开源中国如需转载请紧急联系作者
