Skip to content

Commit 5e12374

Browse files
ahocevarahocevar
authored
Merge pull request #66 from Daniel-Knights/link-tag-support
Link tag support
2 parents 6a99265 + de400d5 commit 5e12374

File tree

4 files changed

+264
-0
lines changed

4 files changed

+264
-0
lines changed

‎README.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,39 @@ When assigned to a variable in the exporting module:
7070

7171
This syntax is also used when referring to types of `@typedef`s and `@enum`s.
7272

73+
### `@link` tags
74+
75+
```js
76+
/**
77+
* {@link Identifier}
78+
*/
79+
80+
/**
81+
* {@link Identifier Link text}
82+
*/
83+
84+
/**
85+
* {@link Identifier.member}
86+
*/
87+
```
88+
89+
To:
90+
91+
```js
92+
/**
93+
* {@link module:path/to/module.Identifier Identifier}
94+
*/
95+
96+
/**
97+
* {@link module:path/to/module.Identifier Link text}
98+
*/
99+
100+
/**
101+
* Member accessors are not currently linked to, just the root identifier:
102+
* {@link module:path/to/module.Identifier Identifier.member}
103+
*/
104+
```
105+
73106
### `typeof type`
74107

75108
```js
@@ -165,6 +198,7 @@ To:
165198
```
166199

167200
To:
201+
168202
```js
169203
/**
170204
* @type {Array}

‎index.js

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -592,6 +592,32 @@ exports.astNodeVisitor = {
592592
);
593593
replace(typeRegex);
594594

595+
const linkWithoutTextRegex = new RegExp(
596+
`@(link (?!https?:))${key}((?:\\.[^\\s}]*)*\\s*\\})`,
597+
'g',
598+
);
599+
const linkMemberAccessorRegex = new RegExp(
600+
`@(link (?!https?:)${key})(?:\\.[^\\s}]*)*([\\s|][^}]*\\})`,
601+
'g',
602+
);
603+
const linkWithTextRegex = new RegExp(
604+
`@(link (?!https?:))${key}([\\s|][^}]*\\})`,
605+
'g',
606+
);
607+
608+
// If link is without text, use key as text
609+
comment.value = comment.value.replace(
610+
linkWithoutTextRegex,
611+
`@$1${key} ${key}$2`,
612+
);
613+
// Remove member accessors from link key
614+
comment.value = comment.value.replace(
615+
linkMemberAccessorRegex,
616+
'@$1$2',
617+
);
618+
619+
replace(linkWithTextRegex);
620+
595621
function replace(regex) {
596622
if (regex.test(comment.value)) {
597623
const identifier = identifiers[key];

‎test/dest/expected.json

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -741,6 +741,190 @@
741741
"memberof": "module:test",
742742
"params": []
743743
},
744+
{
745+
"comment": "/**\n * {@link module:test/sub/NumberStore~NumberStore NumberStore}\n */",
746+
"meta": {
747+
"range": [
748+
1424,
749+
1456
750+
],
751+
"filename": "index.js",
752+
"lineno": 67,
753+
"columnno": 0,
754+
"code": {
755+
"name": "exports.Link",
756+
"type": "VariableDeclaration"
757+
}
758+
},
759+
"description": "{@link module:test/sub/NumberStore~NumberStore NumberStore}",
760+
"name": "Link",
761+
"longname": "module:test.Link",
762+
"kind": "constant",
763+
"memberof": "module:test",
764+
"scope": "static"
765+
},
766+
{
767+
"comment": "",
768+
"meta": {
769+
"range": [
770+
1437,
771+
1455
772+
],
773+
"filename": "index.js",
774+
"lineno": 67,
775+
"columnno": 13,
776+
"code": {
777+
"name": "Link",
778+
"type": "Identifier",
779+
"value": "NumberStore"
780+
}
781+
},
782+
"undocumented": true,
783+
"name": "Link",
784+
"longname": "module:test~Link",
785+
"kind": "constant",
786+
"scope": "inner",
787+
"memberof": "module:test",
788+
"params": []
789+
},
790+
{
791+
"comment": "/**\n * {@link module:test/sub/NumberStore~NumberStore Num}\n */",
792+
"meta": {
793+
"range": [
794+
1493,
795+
1533
796+
],
797+
"filename": "index.js",
798+
"lineno": 72,
799+
"columnno": 0,
800+
"code": {
801+
"name": "exports.LinkWithText",
802+
"type": "VariableDeclaration"
803+
}
804+
},
805+
"description": "{@link module:test/sub/NumberStore~NumberStore Num}",
806+
"name": "LinkWithText",
807+
"longname": "module:test.LinkWithText",
808+
"kind": "constant",
809+
"memberof": "module:test",
810+
"scope": "static"
811+
},
812+
{
813+
"comment": "",
814+
"meta": {
815+
"range": [
816+
1506,
817+
1532
818+
],
819+
"filename": "index.js",
820+
"lineno": 72,
821+
"columnno": 13,
822+
"code": {
823+
"name": "LinkWithText",
824+
"type": "Identifier",
825+
"value": "NumberStore"
826+
}
827+
},
828+
"undocumented": true,
829+
"name": "LinkWithText",
830+
"longname": "module:test~LinkWithText",
831+
"kind": "constant",
832+
"scope": "inner",
833+
"memberof": "module:test",
834+
"params": []
835+
},
836+
{
837+
"comment": "/**\n * {@link module:test/sub/NumberStore~NumberStore NumberStore.getNumber}\n */",
838+
"meta": {
839+
"range": [
840+
1576,
841+
1626
842+
],
843+
"filename": "index.js",
844+
"lineno": 77,
845+
"columnno": 0,
846+
"code": {
847+
"name": "exports.LinkWithMemberAccessor",
848+
"type": "VariableDeclaration"
849+
}
850+
},
851+
"description": "{@link module:test/sub/NumberStore~NumberStore NumberStore.getNumber}",
852+
"name": "LinkWithMemberAccessor",
853+
"longname": "module:test.LinkWithMemberAccessor",
854+
"kind": "constant",
855+
"memberof": "module:test",
856+
"scope": "static"
857+
},
858+
{
859+
"comment": "",
860+
"meta": {
861+
"range": [
862+
1589,
863+
1625
864+
],
865+
"filename": "index.js",
866+
"lineno": 77,
867+
"columnno": 13,
868+
"code": {
869+
"name": "LinkWithMemberAccessor",
870+
"type": "Identifier",
871+
"value": "NumberStore"
872+
}
873+
},
874+
"undocumented": true,
875+
"name": "LinkWithMemberAccessor",
876+
"longname": "module:test~LinkWithMemberAccessor",
877+
"kind": "constant",
878+
"scope": "inner",
879+
"memberof": "module:test",
880+
"params": []
881+
},
882+
{
883+
"comment": "/**\n * {@link module:test/sub/NumberStore~NumberStore Num}\n */",
884+
"meta": {
885+
"range": [
886+
1673,
887+
1730
888+
],
889+
"filename": "index.js",
890+
"lineno": 82,
891+
"columnno": 0,
892+
"code": {
893+
"name": "exports.LinkWithMemberAccessorAndText",
894+
"type": "VariableDeclaration"
895+
}
896+
},
897+
"description": "{@link module:test/sub/NumberStore~NumberStore Num}",
898+
"name": "LinkWithMemberAccessorAndText",
899+
"longname": "module:test.LinkWithMemberAccessorAndText",
900+
"kind": "constant",
901+
"memberof": "module:test",
902+
"scope": "static"
903+
},
904+
{
905+
"comment": "",
906+
"meta": {
907+
"range": [
908+
1686,
909+
1729
910+
],
911+
"filename": "index.js",
912+
"lineno": 82,
913+
"columnno": 13,
914+
"code": {
915+
"name": "LinkWithMemberAccessorAndText",
916+
"type": "Identifier",
917+
"value": "NumberStore"
918+
}
919+
},
920+
"undocumented": true,
921+
"name": "LinkWithMemberAccessorAndText",
922+
"longname": "module:test~LinkWithMemberAccessorAndText",
923+
"kind": "constant",
924+
"scope": "inner",
925+
"memberof": "module:test",
926+
"params": []
927+
},
744928
{
745929
"comment": "/** @ignore */",
746930
"meta": {

‎test/src/index.js

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,3 +60,23 @@ export const bracketNotation = 1;
6060

6161
/** @type {[number, [number, string], "[number, boolean]"]} */
6262
export const nesteedTuples = [1, [1, 'a'], '[number, boolean]'];
63+
64+
/**
65+
* {@link NumberStore}
66+
*/
67+
export const Link = NumberStore;
68+
69+
/**
70+
* {@link NumberStore Num}
71+
*/
72+
export const LinkWithText = NumberStore;
73+
74+
/**
75+
* {@link NumberStore.getNumber}
76+
*/
77+
export const LinkWithMemberAccessor = NumberStore;
78+
79+
/**
80+
* {@link NumberStore.getNumber Num}
81+
*/
82+
export const LinkWithMemberAccessorAndText = NumberStore;

0 commit comments

Comments
 (0)