It would be useful to add an @example tag which
  would be a standard place for engineers/writers
  to add a code example to doc comments.
  An @example tag could contain a code fragment,
  a compilable example, a link to a shared example,
  or a link to a separate example page.

  Some packages that currently have dedicated writers,
  such as Swing, would make use of this tag right away.

  A possible long-term goal would be for each class
  doc comment to have a compilable example.