Skip to content

Commit 41dfa7e

Browse files
songyumengsongyumeng
committed
【update】jsdoc新增@Usage标签用做介绍每个文件的引入方式
1 parent 8d2806a commit 41dfa7e

7 files changed

Lines changed: 109 additions & 12 deletions

File tree

‎.editorconfig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
root = true
33

44
[*]
5-
end_of_line = crlf
5+
end_of_line = lf
66
trim_trailing_whitespace = true
77
insert_final_newline = true
88
charset = utf-8

‎build/jsdocs/classic/docs.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,9 @@
3030
"monospaceLinks": false,
3131
"default": {
3232
"outputSourceFiles": false
33-
}
34-
//"applicationName": "iClient Classic"
33+
},
34+
"namespace": "SuperMap",
35+
"npm":"@supermap/iclient-classic",
36+
"cdn":"https://iclient.supermap.io/dist/classic/iclient-classic.js"
3537
}
3638
}

‎build/jsdocs/leaflet/docs.json‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,13 +27,18 @@
2727
]
2828

2929
},
30-
"plugins": ["plugins/markdown","../plugins/factoryFunction"],
30+
"plugins": ["plugins/markdown","../plugins/usage"],
31+
"markdown": {
32+
"tags": ["usage"]
33+
},
3134
"templates": {
3235
"cleverLinks": true,
3336
"monospaceLinks": true,
3437
"default": {
3538
"outputSourceFiles": false
36-
}
37-
//"applicationName": "iClient for Leaflet"
39+
},
40+
"namespace": "L.supermap",
41+
"npm":"@supermap/iclient-leaflet",
42+
"cdn":"https://iclient.supermap.io/dist/leaflet/iclient-leaflet.js"
3843
}
3944
}

‎build/jsdocs/mapboxgl/docs.json‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,18 @@
2525
"src/common/overlay/levelRenderer"
2626
]
2727
},
28-
"plugins": ["plugins/markdown"],
28+
"plugins": ["plugins/markdown","../plugins/usage"],
29+
"markdown": {
30+
"tags": ["usage"]
31+
},
2932
"templates": {
3033
"cleverLinks": true,
3134
"monospaceLinks": true,
3235
"default": {
3336
"outputSourceFiles": false
34-
}
35-
//"applicationName": "iClient for MapboxGL"
37+
},
38+
"namespace": "mapboxgl.supermap",
39+
"npm":"@supermap/iclient-mapboxgl",
40+
"cdn":"https://iclient.supermap.io/dist/mapboxgl/iclient-mapboxgl.js"
3641
}
3742
}

‎build/jsdocs/openlayers/docs.json‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,18 @@
2525
"src/common/overlay/levelRenderer"
2626
]
2727
},
28-
"plugins": ["plugins/markdown"],
28+
"plugins": ["plugins/markdown","../plugins/usage"],
29+
"markdown": {
30+
"tags": ["usage"]
31+
},
2932
"templates": {
3033
"cleverLinks": false,
3134
"monospaceLinks": false,
3235
"default": {
3336
"outputSourceFiles": false
34-
}
35-
//"applicationName": "iClient for OpenLayers"
37+
},
38+
"namespace": "ol.supermap",
39+
"npm":"@supermap/iclient-ol",
40+
"cdn":"https://iclient.supermap.io/dist/openlayers/iclient-ol.js"
3641
}
3742
}

‎build/jsdocs/plugins/usage.js‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
const env = require('jsdoc/lib/jsdoc/env');
2+
3+
const globalParams = env.conf.templates;
4+
exports.defineTags = function (dictionary) {
5+
dictionary.defineTag('usage', {
6+
mustHaveValue: false,
7+
mustNotHaveDescription: false,
8+
canHaveType: false,
9+
canHaveName: false,
10+
onTagged: function (doclet, tag) {
11+
if (tag.value) {
12+
doclet.usage = tag.value;
13+
} else {
14+
const deprecatedClasses = [];
15+
if (doclet.tags) {
16+
for (let index = 0; index < doclet.tags.length; index++) {
17+
const tag = doclet.tags[index];
18+
if (tag.title === 'deprecatedclass') {
19+
deprecatedClasses.push(tag.value);
20+
}
21+
}
22+
}
23+
doclet.usage = {
24+
className: doclet.kind === 'class' ? doclet.name : '',
25+
globalParams,
26+
deprecatedClasses: deprecatedClasses
27+
};
28+
}
29+
}
30+
});
31+
};
32+
33+
exports.handlers = {
34+
parseComplete: function (e) {
35+
const doclets = e.doclets;
36+
let usage = null;
37+
for (let index = 0; index < doclets.length; index++) {
38+
const doclet = doclets[index];
39+
if (doclet.usage && typeof doclet.usage === 'object') {
40+
usage = doclet.usage;
41+
}
42+
if (doclet.meta && doclet.meta.code && doclet.meta.code.type === 'ClassDeclaration' && usage) {
43+
usage.paramsNames = doclet.meta.code.paramnames;
44+
}
45+
}
46+
},
47+
newDoclet: function (e) {
48+
var usage = e.doclet.usage;
49+
if (usage && usage.indexOf) {
50+
for (const key in globalParams) {
51+
if (Object.hasOwnProperty.call(globalParams, key)) {
52+
const element = globalParams[key];
53+
e.doclet.usage = e.doclet.usage.replace(`{${key}}`, element);
54+
}
55+
}
56+
}
57+
}
58+
};

‎build/jsdocs/template/tmpl/usage.tmpl‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?js var data = obj; ?>
2+
<?jsif(data && typeof data === 'object'){?>
3+
<pre class="prettyprint">
4+
<code>// 浏览器
5+
&lt;script type="text/javascript" src="<?js= data.globalParams.cdn ?>"&gt;&lt;/script&gt;
6+
&lt;script&gt;
7+
<?js= "new {namespace}.{className}({paramsNames});".replace('{className}',data.className).replace('{namespace}',data.globalParams.namespace).replace('{paramsNames}',data.paramsNames?data.paramsNames.join(', '):'') ?>
8+
9+
// 弃用的写法
10+
<?js data.deprecatedClasses.forEach(deprecatedClass => { ?><?js= "new {deprecatedClass}({paramsNames});".replace('{deprecatedClass}',deprecatedClass).replace('{paramsNames}',data.paramsNames?data.paramsNames.join(', '):'') ?>
11+
<?js }); ?>
12+
&lt;/script&gt;
13+
14+
<span class="nopretty">// ES6 Import</span>
15+
<?js= "import {{className}} from '{npm}';".replace('{className}',data.className).replace('{npm}',data.globalParams.npm) ?>
16+
17+
<?js= "new {className}({paramsNames});".replace('{className}',data.className).replace('{paramsNames}',data.paramsNames?data.paramsNames.join(', '):'') ?>
18+
</code>
19+
</pre>
20+
<?js}else{ ?>
21+
<?js= data ?>
22+
<?js} ?>

0 commit comments

Comments
 (0)