/** @example


         <----- Example of use here ------>

*/

======================================================================

You can output any custom tag using the -tag option.  In this case, use
this command line option:

-tag example:a:"Example:"

This takes the text from an @example tag in all (a) doc comments (field, method. constructor, class, package) and outputs it with the heading "Example:".

This would make the API docs an order of magnitude more useful.
We can use the examples already created for Java Class Libraries.
  xxxxx@xxxxx   1997-10-06

Our current plan is to link to the Java Tutorial wherever possible,
instead of standalone examples.
Patrick Chan is not amenable to having us link the API docs to his 
examples, because it could kill the sales of his book.
  xxxxx@xxxxx   1998-02-05

We should also enable the example to be in a separate file in the 
newly-created "doc-files" directory.   In this case, there would
only be a paragraph and a link to that file:

  @example  This example is <a href="doc-files/buttons.java">a dialog 
            box with two buttons(/a>.
            
  xxxxx@xxxxx   1998-03-16

Where does the example end? I suggest the example terminate 
when another javadoc tag is encountered rather than require 
that it be the last tag in the comment block. 

Yes, the next tag would end the example. This is the rule
for all tags.
-Doug

Yes! Absolutely essential!

Is this available now? I sure can use it right away.

Yes, you can output any custom tag using the -tag option. 
In this 
case, use:this command line option:

-tag example:a:"Example:"

This takes the text from an @example tag in all (a) doc
comments 
(field, method. constructor, class) and outputs it with the
heading "Example:".

I suggest to forms:

1. {@java} public class Example { {@/java}

2. {@java <url>}

Note the first evil example that contains a { without a 
closing } in the example.

I would also like the java source code to by syntax 
highlighted.

With the new -tag, should this bug be closed?

The @example is now part of Doxygen 1.5.5. This is an extremely helpful feature. 
/**
@example <filename>
**/
Clicking on the link produces an HTML page of the code in <filename>.

Also, all distinct @example instances are listed in a seperate "Examples" tab, so the user can see all available examples.