Support package specific javadoc-location attributes

philwebb · rwinch · commit 251448218212 · 2024-09-04T07:35:21.000-07:00
Closes gh-18
diff --git a/README.adoc b/README.adoc
@@ -597,7 +597,27 @@ For example, you can set `javadoc-location` to `xref:api:java` if you publish ja
 
 NOTE: document attributes can be set in your Antora playback under the https://docs.antora.org/antora/latest/playbook/asciidoc-attributes/#attributes-key[attributes key].
 
-You can also override locations on a per-link basis.
+===== Package Specific Locations
+
+You can use package specific `javadoc-location` document attributes if you want to support multiple locations.
+To set a package specific location, add a `javadoc-location-<package>` document attribute.
+The `<package>` should be the java package name with all `.` characters replaced with `-`.
+
+For example, the following will use different locations for `com.example.core` links:
+
+[,asciidoc]
+----
+= Example
+:javadoc-location-com-example-core: {url-example-javadoc}
+
+Please see javadoc:com.example.core.util.MyUtils[]
+----
+
+===== Link Specific Locations
+
+You can override locations on a per-link basis by including the location directly in the link.
+The embedded link must end with a `/`.
+
 For example:
 
 [,asciidoc]
diff --git a/lib/javadoc-extension.js b/lib/javadoc-extension.js
@@ -29,8 +29,10 @@ function parseTarget (target) {
   const reference = lastSlash !== -1 ? target.substring(lastSlash + 1, target.length) : target
   const lastHash = reference.lastIndexOf('#')
   const classReference = lastHash !== -1 ? reference.substring(0, lastHash) : reference
+  const lastDot = classReference.lastIndexOf('.')
+  const packageReference = classReference.substring(0, lastDot)
   const anchor = lastHash !== -1 ? reference.substring(lastHash + 1, reference.length) : undefined
-  return { location, classReference, anchor }
+  return { location, packageReference, classReference, anchor }
 }
 
 function process (document, target, attrs) {
@@ -45,11 +47,23 @@ function process (document, target, attrs) {
 }
 
 function createLinkMarkup (document, target, description, attributes) {
-  const location = target.location || document.getAttribute('javadoc-location', 'xref:attachment$api/java')
+  const location = target.location || getTargetLocation(document, target)
   const text = `${link(location, target)}[${description},role=apiref]`
   return { text, opts: { attributes } }
 }
 
+function getTargetLocation (document, target) {
+  let name = target.packageReference
+  let lastDot = name.lastIndexOf('.')
+  while (lastDot > 0) {
+    const location = document.getAttribute('javadoc-location-' + name.replaceAll('.', '-'))
+    if (location) return location
+    name = name.substring(0, lastDot)
+    lastDot = name.lastIndexOf('.')
+  }
+  return document.getAttribute('javadoc-location', 'xref:attachment$api/java')
+}
+
 function link (location, target) {
   let link = location
   link = !link.endsWith('/') ? link + '/' : link
diff --git a/test/javadoc-extension-test.js b/test/javadoc-extension-test.js
@@ -131,6 +131,34 @@ describe('javadoc-extension', () => {
       )
     })
 
+    it('should convert with specified location when has package specific javadoc-location attributes', () => {
+      const input = heredoc`
+        = Page Title
+        :javadoc-location: xref:api:java
+        :javadoc-location-com-example: xref:api:e
+        :javadoc-location-com-example-one: xref:api:e1
+        :javadoc-location-com-example-one-two: xref:api:e12
+
+        javadoc:org.example.MyClass1[]
+        javadoc:com.example.one.two.three.MyClass2[]
+        javadoc:com.example.one.three.three.MyClass3[]
+        javadoc:com.example.test.MyClass4[]
+        `
+      const actual = run(input)
+      expect(actual).to.include(
+        '<a href="https://docs.example.com/api/java/org/example/MyClass1.html" class="xref page apiref"><code>MyClass1</code></a>'
+      )
+      expect(actual).to.include(
+        '<a href="https://docs.example.com/api/e12/com/example/one/two/three/MyClass2.html" class="xref page apiref"><code>MyClass2</code></a>'
+      )
+      expect(actual).to.include(
+        '<a href="https://docs.example.com/api/e1/com/example/one/three/three/MyClass3.html" class="xref page apiref"><code>MyClass3</code></a>'
+      )
+      expect(actual).to.include(
+        '<a href="https://docs.example.com/api/e/com/example/test/MyClass4.html" class="xref page apiref"><code>MyClass4</code></a>'
+      )
+    })
+
     it('should convert with specified location when has xref location in macro', () => {
       const input = heredoc`
         = Page Title
