The @code tag is a great convenience for including source code in javadoc, especially when working with the generics syntax where "<" and ">" should be awkwardly escaped in html. However, while @code works well for one-line code samples, there are some source code constructs which confuse the @code tag. For example, this code sample from javax.lang.model.element.NestingKind cannot currently be placed in a single @code tag:

 import java.lang.annotation.*;
 import static java.lang.annotation.RetentionPolicy.*;
 import javax.lang.model.element.*;
 import static javax.lang.model.element.NestingKind.*;
 
 @Nesting(TOP_LEVEL)
 public class NestingExamples {
     @Nesting(MEMBER)
     static class MemberClass1{}
 
     @Nesting(MEMBER)
     class MemberClass2{}
 
     public static void main(String... argv) {
         @Nesting(LOCAL)
         class LocalClass{};
 
         Class<?>[] classes = {
             NestingExamples.class,
             MemberClass1.class,
             MemberClass2.class,
             LocalClass.class
         };
 
         for(Class<?> clazz : classes) {
             System.out.format("%s is %s%n",
                               clazz.getName(),
                               clazz.getAnnotation(Nesting.class).value());
         }
     }
 }
 
 @Retention(RUNTIME)
 @interface Nesting {
     NestingKind value();
 }

Various errors related to the annotations are reported if a single @code tag is used.