Preview APIs are a Java/JDK specific feature, but there is interest in using javadoc support for documenting preview features in other projects. We can provide a hidden javadoc option to allow using a javadoc tag as an alternative way of marking elements as preview APIs.

The feature uses two undocumented javadoc options to mark API elements as preview features and provide custom preview notes for them:

  --preview-feature-tag previewFeature
  Defines block tag @previewFeature as marker for preview elements. The block tag should provide a description of the preview feature.

  --preview-note-tag previewNote
  Defines block tag @previewNote as provider of a preview note for a preview element. The block tag should contain the preview note for the element.

Both block tags should be defined as Taglets using the -taglet and -tagletpath options. The tags should not produce any output as the tag contents are used by javadoc.

While preview note tags may contain rich content such as HTML elements and nested tags, preview feature tags can only contain plain text.