Uploaded image for project: 'Java Driver'
  1. Java Driver
  2. JAVA-4613

Find alternative to Javadoc taglets

    • Type: Icon: Improvement Improvement
    • Resolution: Unresolved
    • Priority: Icon: Unknown Unknown
    • None
    • Affects Version/s: None
    • Component/s: Documentation
    • None

      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.

            Assignee:
            Unassigned Unassigned
            Reporter:
            jeff.yemin@mongodb.com Jeffrey Yemin
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated: