Skip to content

Commit 90f5bc1

Browse files
rwinchphilwebb
rwinch
and
philwebb
committed
Allow non-monospace javadoc link text
Closes gh-17 Co-authored-by: Phillip Webb <[email protected]>
1 parent d23dc05 commit 90f5bc1

3 files changed

Lines changed: 50 additions & 36 deletions

File tree

‎README.adoc‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -642,11 +642,9 @@ You can also specify directly specify link text if the existing formats are not
642642

643643
[,asciidoc]
644644
----
645-
See javadoc:com.example.MyClass$Builder[Builder] for details.
645+
javadoc:com.example.MyClass$Builder[See `Builder` for details].
646646
----
647647

648-
NOTE: The link text is _always_ wrapped in a `<code>` block so you should not use backticks.
649-
650648
==== Anchors
651649

652650
Anchors may be used to link to a specific part of a javadoc page.

‎lib/javadoc-extension.js‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,8 @@ function createExtensionGroup () {
1515
this.inlineMacro(function () {
1616
this.named('javadoc')
1717
this.process((parent, target, attrs) => {
18-
const text = process(parent.getDocument(), parseTarget(target), attrs)
19-
return this.createInline(parent, 'quoted', text, {
20-
type: 'monospaced',
21-
})
18+
const processed = process(parent.getDocument(), parseTarget(target), attrs)
19+
return this.createInline(parent, 'quoted', processed.text, processed.opts)
2220
})
2321
})
2422
}
@@ -36,11 +34,20 @@ function parseTarget (target) {
3634
}
3735

3836
function process (document, target, attrs) {
39-
const location = target.location || document.getAttribute('javadoc-location', 'xref:attachment$api/java')
37+
const description = attrs.$positional?.[0]
38+
if (description) {
39+
// Substitutions have already been applied to positional attributes
40+
return createLinkMarkup(document, target, description, { subs: 'none' })
41+
}
4042
const format = attrs.format || document.getAttribute('javadoc-format', 'short')
41-
const linkLocation = link(location, target)
42-
const linkDescription = applyFormat(target, format, attrs.$positional)
43-
return `${linkLocation}['${linkDescription}',role=apiref]`
43+
const formattedDescription = applyFormat(target, format).replaceAll(',', ',')
44+
return createLinkMarkup(document, target, formattedDescription, { subs: 'normal' })
45+
}
46+
47+
function createLinkMarkup (document, target, description, attributes) {
48+
const location = target.location || document.getAttribute('javadoc-location', 'xref:attachment$api/java')
49+
const text = `${link(location, target)}[${description},role=apiref]`
50+
return { text, opts: { attributes } }
4451
}
4552

4653
function link (location, target) {
@@ -51,26 +58,23 @@ function link (location, target) {
5158
return link
5259
}
5360

54-
function applyFormat (target, format, positionalAttrs, annotationAnchor) {
55-
if (positionalAttrs?.[0]) return positionalAttrs?.[0]
61+
function applyFormat (target, format, annotationAnchor) {
5662
switch (format) {
5763
case 'full':
58-
return className(target.classReference, 'full') + anchorText(target.anchor, format, annotationAnchor)
64+
return '`' + className(target.classReference, 'full') + anchorText(target.anchor, format, annotationAnchor) + '`'
5965
case 'annotation':
60-
return '@' + className(target.classReference, 'short') + anchorText(target.anchor, format)
66+
return '`@' + className(target.classReference, 'short') + anchorText(target.anchor, format) + '`'
6167
default:
62-
return className(target.classReference, 'short') + anchorText(target.anchor, format)
68+
return '`' + className(target.classReference, 'short') + anchorText(target.anchor, format) + '`'
6369
}
6470
}
6571

6672
function anchorText (anchor, format, annotationAnchor) {
6773
if (!anchor) return ''
6874
if (format === 'annotation' || annotationAnchor) anchor = anchor.replaceAll('()', '')
6975
const methodMatch = METHOD_REGEX.exec(anchor)
70-
if (methodMatch) {
71-
return '.' + methodText(methodMatch[1], methodMatch[2], format)
72-
}
73-
return '.' + anchor
76+
const result = '.' + (methodMatch ? methodText(methodMatch[1], methodMatch[2], format) : anchor)
77+
return result.replaceAll(',', '+++,+++')
7478
}
7579

7680
function methodText (name, params, format) {

‎test/javadoc-extension-test.js‎

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ describe('javadoc-extension', () => {
101101
`
102102
const actual = run(input)
103103
expect(actual).to.include(
104-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref">MyClass</a></code>'
104+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref"><code>MyClass</code></a>'
105105
)
106106
})
107107

@@ -114,7 +114,7 @@ describe('javadoc-extension', () => {
114114
`
115115
const actual = run(input)
116116
expect(actual).to.include(
117-
'<code><a href="https://docs.example.com/api/java/com/example/MyClass.html" class="xref page apiref">MyClass</a></code>'
117+
'<a href="https://docs.example.com/api/java/com/example/MyClass.html" class="xref page apiref"><code>MyClass</code></a>'
118118
)
119119
})
120120

@@ -127,7 +127,7 @@ describe('javadoc-extension', () => {
127127
`
128128
const actual = run(input)
129129
expect(actual).to.include(
130-
'<code><a href="https://docs.example.com/api/java/com/example/MyClass.html" class="xref page apiref">MyClass</a></code>'
130+
'<a href="https://docs.example.com/api/java/com/example/MyClass.html" class="xref page apiref"><code>MyClass</code></a>'
131131
)
132132
})
133133

@@ -139,7 +139,7 @@ describe('javadoc-extension', () => {
139139
`
140140
const actual = run(input)
141141
expect(actual).to.include(
142-
'<code><a href="https://docs.example.com/api/java/com/example/MyClass.html" class="xref page apiref">MyClass</a></code>'
142+
'<a href="https://docs.example.com/api/java/com/example/MyClass.html" class="xref page apiref"><code>MyClass</code></a>'
143143
)
144144
})
145145

@@ -151,7 +151,7 @@ describe('javadoc-extension', () => {
151151
`
152152
const actual = run(input)
153153
expect(actual).to.include(
154-
'<code><a href="https://javadoc.example.com/latest/com/example/MyClass.html" class="apiref">MyClass</a></code>'
154+
'<a href="https://javadoc.example.com/latest/com/example/MyClass.html" class="apiref"><code>MyClass</code></a>'
155155
)
156156
})
157157

@@ -163,7 +163,7 @@ describe('javadoc-extension', () => {
163163
`
164164
const actual = run(input)
165165
expect(actual).to.include(
166-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref">com.example.MyClass</a></code>'
166+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref"><code>com.example.MyClass</code></a>'
167167
)
168168
})
169169

@@ -175,7 +175,7 @@ describe('javadoc-extension', () => {
175175
`
176176
const actual = run(input)
177177
expect(actual).to.include(
178-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyAnnotation.html" class="xref page apiref">@MyAnnotation</a></code>'
178+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyAnnotation.html" class="xref page apiref"><code>@MyAnnotation</code></a>'
179179
)
180180
})
181181

@@ -187,7 +187,7 @@ describe('javadoc-extension', () => {
187187
`
188188
const actual = run(input)
189189
expect(actual).to.include(
190-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref">MyClass</a></code>'
190+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref"><code>MyClass</code></a>'
191191
)
192192
})
193193

@@ -200,19 +200,19 @@ describe('javadoc-extension', () => {
200200
`
201201
const actual = run(input)
202202
expect(actual).to.include(
203-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref">com.example.MyClass</a></code>'
203+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref"><code>com.example.MyClass</code></a>'
204204
)
205205
})
206206

207207
it('should convert with specified text when has link text', () => {
208208
const input = heredoc`
209209
= Page Title
210210
211-
javadoc:com.example.MyClass$Builder[Builder]
211+
javadoc:com.example.MyClass$Builder[\`Builder\`]
212212
`
213213
const actual = run(input)
214214
expect(actual).to.include(
215-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.Builder.html" class="xref page apiref">Builder</a></code>'
215+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.Builder.html" class="xref page apiref"><code>Builder</code></a>'
216216
)
217217
})
218218

@@ -224,7 +224,7 @@ describe('javadoc-extension', () => {
224224
`
225225
const actual = run(input)
226226
expect(actual).to.include(
227-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.Builder.html" class="xref page apiref">MyClass.Builder</a></code>'
227+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.Builder.html" class="xref page apiref"><code>MyClass.Builder</code></a>'
228228
)
229229
})
230230

@@ -236,7 +236,7 @@ describe('javadoc-extension', () => {
236236
`
237237
const actual = run(input)
238238
expect(actual).to.include(
239-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html#run(java.lang.Class,java.lang.String)" class="xref page apiref">MyClass.run(Class, String)</a></code>'
239+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html#run(java.lang.Class,java.lang.String)" class="xref page apiref"><code>MyClass.run(Class, String)</code></a>'
240240
)
241241
})
242242

@@ -248,7 +248,7 @@ describe('javadoc-extension', () => {
248248
`
249249
const actual = run(input)
250250
expect(actual).to.include(
251-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html#run(java.lang.Class,java.lang.String...)" class="xref page apiref">MyClass.run(Class, String&#8230;&#8203;)</a></code>'
251+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html#run(java.lang.Class,java.lang.String&#8230;&#8203;)" class="xref page apiref"><code>MyClass.run(Class, String&#8230;&#8203;)</code></a>'
252252
)
253253
})
254254

@@ -260,7 +260,7 @@ describe('javadoc-extension', () => {
260260
`
261261
const actual = run(input)
262262
expect(actual).to.include(
263-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html#MY_CONST" class="xref page apiref">MyClass.MY_CONST</a></code>'
263+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html#MY_CONST" class="xref page apiref"><code>MyClass.MY_CONST</code></a>'
264264
)
265265
})
266266

@@ -272,7 +272,19 @@ describe('javadoc-extension', () => {
272272
`
273273
const actual = run(input)
274274
expect(actual).to.include(
275-
'<code><a href="https://docs.example.com/_attachments/api/java/com/example/MyAnnotation.html#format()" class="xref page apiref">@MyAnnotation.format</a></code>'
275+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyAnnotation.html#format()" class="xref page apiref"><code>@MyAnnotation.format</code></a>'
276+
)
277+
})
278+
279+
it('should convert with own formatted text', () => {
280+
const input = heredoc`
281+
= Page Title
282+
283+
javadoc:com.example.MyClass[Take a _look_ at \`MyClass\` for *details*]
284+
`
285+
const actual = run(input)
286+
expect(actual).to.include(
287+
'<a href="https://docs.example.com/_attachments/api/java/com/example/MyClass.html" class="xref page apiref">Take a <em>look</em> at <code>MyClass</code> for <strong>details</strong></a>'
276288
)
277289
})
278290
})

0 commit comments

Comments
 (0)