【API】 jsdoc优化引入外部类型

songyumeng · songyumeng · commit 72ace0ec2afd · 2018-04-25T16:27:38.000+08:00
diff --git a/build/jsdocs/leaflet/categories.json b/build/jsdocs/leaflet/categories.json
diff --git a/build/jsdocs/mapboxgl/categories.json b/build/jsdocs/mapboxgl/categories.json
diff --git a/build/jsdocs/openlayers/categories.json b/build/jsdocs/openlayers/categories.json
diff --git a/build/jsdocs/plugins/linkdoc.js b/build/jsdocs/plugins/linkdoc.js
@@ -2,6 +2,7 @@
 
 var logger = require('jsdoc/util/logger');
 var env = require('jsdoc/env');
+var typeLinks = require('../template/typeLinkExt').typeLinks;
 exports.handlers = {
     newDoclet: function (e) {
         if (e.doclet.augments) {
@@ -23,14 +24,24 @@ exports.handlers = {
         if (e.doclet.params) {
             for (var i = 0; i < e.doclet.params.length; i++) {
                 var a = e.doclet.params[i].description;
-                if (a && a.indexOf("@linkdoc")) {
+                if (a && a.indexOf("@linkdoc") > -1) {
                     var reg = new RegExp("@(linkdoc.*?)/");
                     var match = a.match(reg);
                     if (match) {
-                        var str="@" + match[1] + "/";
-                        e.doclet.params[i].description = a.replace(new RegExp(str,'g'), "@link "+ env.conf.tags[match[1]]);
+                        var str = "@" + match[1] + "/";
+                        e.doclet.params[i].description = a.replace(new RegExp(str, 'g'), "@link " + env.conf.tags[match[1]]);
+                    }
+                } else if (a && a.indexOf("@link") > -1) {
+                    var patt = /{@link (\S*)}/g;
+                    var result;
+                    while ((result = patt.exec(a)) != null) {
+                        var link = result[1];
+                        if (link && typeLinks[link]) {
+                            e.doclet.params[i].description = e.doclet.params[i].description.replace(result[0], "[" + link + "]{@link " + typeLinks[result[1]] + "}");
+                        }
                     }
                 }
+
             }
         }
     }
diff --git a/build/jsdocs/template/publish.js b/build/jsdocs/template/publish.js
@@ -7,7 +7,8 @@ var template = require('jsdoc/template'),
     handle = require('jsdoc/util/error').handle,
     helper = require('jsdoc/util/templateHelper'),
     logger = require('jsdoc/util/logger'),
-    
+    typeLinks= require('./typeLinkExt').typeLinks,
+   
     _ = require('underscore'),
     htmlsafe = helper.htmlsafe,
     linkto = helper.linkto,
@@ -365,7 +366,7 @@ exports.publish = function (taffyData, opts, tutorials) {
 
     var globalUrl = helper.getUniqueFilename('global');
     helper.registerLink('global', globalUrl);
-
+    view.typeLinks=typeLinks;
     // set up templating
     view.layout = 'layout.tmpl';
 
diff --git a/build/jsdocs/template/tmpl/container.tmpl b/build/jsdocs/template/tmpl/container.tmpl
@@ -50,12 +50,12 @@
     
     <?js if (doc.augments && doc.augments.length) { ?>
         <h3 class="subsection-title">Extends</h3>
-        
         <ul><?js doc.augments.forEach(function(a) { ?>
             <?js if (a) { ?>
             <?js  array=a.split('{'); ?>
             <?js if (array.length == 1) {  ?>
-            <li><?js= self.linkto(a, a)  ?></li>
+            <?js var url=self.typeLinks[a]||a;  ?>
+            <li><?js= self.linkto(url, a)  ?></li>
             <?js }else{ ?>
             <li><?js= self.linkto(array[1].substring(0,array[1].length-1),array[0]) ?></li>
             <?js } ?>
diff --git a/build/jsdocs/template/tmpl/type.tmpl b/build/jsdocs/template/tmpl/type.tmpl
@@ -2,6 +2,14 @@
 	var data = obj;
     var self = this;
     data.forEach(function(name, i) { ?>
-<span class="param-type"><?js= self.linkto(name, self.htmlsafe(name)) ?></span>
+<span class="param-type"><?js=
+function(){
+   if(name&&self.typeLinks&&self.typeLinks[name]){
+      return self.linkto(self.typeLinks[name],name);
+    } else{
+return self.linkto(name, self.htmlsafe(name)) 
+    } 
+}()
+?></span>
 <?js if (i < data.length-1) { ?>|<?js } ?>
 <?js }); ?>
diff --git a/build/jsdocs/template/typeLinkExt.js b/build/jsdocs/template/typeLinkExt.js
@@ -0,0 +1,6 @@
+var olapi = "https://openlayers.org/en/latest/apidoc/";
+var typeLinks = {
+    "ol.Map": olapi + "ol.Map.html",
+    "ol.View": olapi + "ol.View.html"
+}
+exports.typeLinks = typeLinks;
diff --git a/src/openlayers/overlay/vectortile/MapboxStyles.js b/src/openlayers/overlay/vectortile/MapboxStyles.js
@@ -19,12 +19,12 @@ import {
  * @param {Object} options 初始化参数。<br>
  * @param {string | undefined} options.url - iServer UGCV5(MVT) 地图服务地址，例如 `http://localhost:8090/iserver/services/map-mvt-test/rest/maps/test` , 与 `options.style` 互斥，优先级低于 `options.style`。
  * @param {Object | undefined} options.style - Mapbox style 对象。 与 `options.url` 互斥，优先级高于 `options.url`。
- * @param {Array.<number>} options.resolutions - 地图分辨率数组，用于映射zoom值。通常情況与地图的 [ol.View]{@linkdoc-openlayers/ol.View} 的分辨率一致。</br>
+ * @param {Array.<number>} options.resolutions - 地图分辨率数组，用于映射zoom值。通常情況与地图的 {@link ol.View} 的分辨率一致。</br>
  * 默认值为`[78271.51696402048,39135.75848201024, 19567.87924100512,9783.93962050256,4891.96981025128,2445.98490512564, 1222.99245256282,611.49622628141,305.748113140705,152.8740565703525, 76.43702828517625,38.21851414258813,19.109257071294063,9.554628535647032, 4.777314267823516,2.388657133911758,1.194328566955879,0.5971642834779395, 0.29858214173896974,0.14929107086948487,0.07464553543474244]`。
  * @param {!(string|Array.<string>)} options.source - Mapbox Style `source` key值或者 `layer`的 id 数组。
  * 当配置`source` key值时，source为该值的layer会被加载；
  * 当配置为`layer`的 id 数组时，指定的layer会被加载，注意被指定的layer需要有相同的source。
- * @param {ol.Map} options.map - {ol.supermap.VectorTileStyles}Openlayers 地图对象，仅用于填充Mapbox Style中的 `background`,如没有配置`background`可不设置该参数。
+ * @param {ol.Map} options.map - Openlayers 地图对象，仅用于填充Mapbox Style中的 `background`,如没有配置`background`可不设置该参数。
  * @example
  *  var mbStyle = new ol.supermap.MapboxStyles({
             url: url,
