[JAVA-4613] Find alternative to Javadoc taglets Created: 16/May/22  Updated: 10/Oct/22

Status: Backlog
Project: Java Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Unknown
Reporter: Jeffrey Yemin Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

We use taglets largely to reduce the boilerplate Javadoc necessary to link to external MongoDB documentation. So

@mongodb.atlas.manual atlas-search/autocomplete/

expands to something like:

<dl><dt><span class="strong">MongoDB Atlas documentation</span></dt><dd><a href='https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/'>autocomplete operator</a></dd></dl>

While convenient for driver authors, it's not so good for any user who primarily views our Javadoc in the IDE. The IDE does not have access to our custom taglet processor, so in the rendered view the taglet is completely hidden. And even in the edit view, the partial URI makes it impossible to copy and paste into a browser to view the documentation. The user would have to know the URI prefix to make a complete URL.

We should consider replacing all of our taglets with regular HTML so that the Javadoc is more usable in the IDE. To ease pain on driver authors, we can consider a commit time process (using commit hooks) that does the equivalent taglet processing.


Generated at Thu Feb 08 09:02:31 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.