RFE JavaDoc tags @snippet or @code tage to represent example code

Name: ddT132432 Date: 09/05/2001


Classic VM (build JDK-1.2.2_005, native threads, symcjit

The ability to learn Java is directly proportional to the time it takes to get
from reading and understanding the documentation to get to a working piece of
code. I think it would help the Java community immensely if we could get
developers to easily dump in some sample code demonstrating the method being
documented. Also, examples are like a thousand words, in they tend to shorten
or improve the overall documentation.

My suggestion is to the JavaDoc developers is to include a tag like @snippet or
@code. This tag would serve two purposes. First, it would encourage and remind
developers to include sample code snippets in their JavaDoc. Second, it would
make it easier by formatting that section of JavaDoc as source code
automatically, without the author having to insert "<code>" html tags (or
whatever other tags it would require) to get the documentation to appear as
mono-space example code (without line wrap). This formatting would continue
until another @ tag was encountered or the end of the JavaDoc section was
encountered.
 
My belief is that more developers would just dump in some sample code showing
how to use a method (or a class) if the process were easier. By creating this
tag type just for sample code, I believe would encourage and expand the use of
JavaDoc especially with source code samples.
(Review ID: 131400)
======================================================================