philwebb
commented
1 week ago Unfortunately it seems like title isn't a valid option on a link so we can't use it. I also can't see any easy way to attach data-... attributes.
The best I've come up with so far is to attach a pseudo class to the outer <code> element. Code for that is in https://github.com/philwebb/asciidoctor-extensions/commit/f819671e51d94bd8bbb68812b5dea8af1e2c622d.
Initial prototype code is at https://github.com/rwinch/asciidoctor-extensions/tree/javadoc-extension
The idea behind the extension is to easily convert links of the form
javadoc:com.example.MyClass[]to a styled link to the javadoc HTML.Xref Defaults
The default link conversion will depend on the project. The most common formats will be:
xref:attachment$api/java/com/example/MyClass.htmlxref:api:java/com/example/MyClass.htmlText Formats
We should allow the format of the link text to be changed as needed. We should support the following:
com.example.MyClass->MyClasscom.example.MyClass->com.example.MyClasscom.example.MyAnnotation->@MyAnnotationFormats could be specified as an attribute:
javadoc:com.example.MyClass[format=full]Title and Role
We should create links with
titleandroleattributes so that we can have our UI render them nicely and perhaps offer hover hints showing the fully qualified name. E.g.xref:api:java/com/example/MyClass.html[MyClass,role=javadocref,title=com.example.MyClass]Alternative Link Formats
We may need to deal with alternative link formats if we want to support xrefs to other modules, components or external locations. One idea would be to support a prefix in the reference. E.g.
javadoc:xref:maven-plugin:api/java/com.example.MyClass[](link to different module in project)javadoc:xref:framework:attachment$api/java/com.example.MyClass[](link to different component)javadoc:https://docs.example.com/jdoc/com.example.MyClass[](link to external site)Alternative Text
User might want to use their own link text.
javadoc:com.example.MyClass[see this class for details]Method/Field References
We might want to consider if we should support links to methods or fields inside the javadoc. For example:
javadoc:com.example.MyClass#myMethod(java.lang.String)[]