Multiple line code example in Javadoc comment

Question

I have a small code example I want to include in the Javadoc comment for a method            -- ex  looping through List of Map objects --     lt code gt     for  int i   0  i  lt  list size    i              Map map    Map list get i           System out println map get  wordID             System out println map get  word              lt  code gt          param query - select statement     return List of Map objects       The problem is the code example shows up in the Javadoc with no line breaks making it hard to read     -- ex  looping through List of Map objects -- for  int i   0  i list size    i      Map map    Map list get i   System out println map get  wordID     System out println map get  word        Parameters query - - select statement  Returns  List of Map objects    I guess I am wrong in assuming the code tag would handle line breaks   What is the best way to format code examples in Javadoc comments

User · Answer

The java source has lots of good examples for this  Here s an example from the head of  String java            is equivalent to      lt p gt  lt blockquote gt  lt pre gt         char data       a    b    c           String str   new String data       lt  pre gt  lt  blockquote gt  lt p gt     Here are some more examples of how strings can be used      lt p gt  lt blockquote gt  lt pre gt         System out println  abc           String cde    cde          System out println  abc    cde          String c    abc  substring 2 3          String d   cde substring 1  2       lt  pre gt  lt  blockquote gt

User · Answer

I had a really tough time with including a specific code example in a javadoc comment  I d like to share this one  Please note the following    usage of old  lt code gt  - tag to prevent the curly brackets from being interpreted usage of  new    code      - tag to get the generics included in the output escaping of the   sign in  Override via    literal   Override  because javadoc generator  tilts  there due to the fact that the   goes directly after an opening curly bracket remove one space in front of   code and   literal  to compensate inner spaces and keep the alignment   javadoc code        this methods adds a specific translator from one type to another type        i e       lt pre gt       lt code gt new BeanTranslator Builder          translate          new  code Translator lt String  Integer gt   String class  Integer class              literal   Override           public Integer translate String instance                return Integer valueOf instance                        build         lt  code gt       lt  pre gt       param translator        gets printed as   new BeanTranslator Builder      translate      new Translator lt String  Integer gt  String class  Integer class          Override       public Integer translate String instance            return Integer valueOf instance                build

User · Answer

In Visual Studio Code at least  you can force a Javadoc comment to respect line-breaks by wrapping it in triple-backticks  as seen below          markdown    This content is rendered in  partial  markdown         For example   italic  and   bold   text works  but  links  https   www google com  do not     Bonus  it keeps single line-breaks  as seen between this line and the previous

User · Answer

Enclose your multiline code with  lt pre gt  lt  pre gt  tags

User · Answer

lt blockquote gt  lt pre gt       code    public Foo final Class lt   gt  klass           super           this klass   klass                lt  pre gt  lt  blockquote gt           lt pre  gt  is required for preserving lines    code must has its own line  lt blockquote  gt  is just for indentation    public Foo final Class lt   gt  klass        super        this klass   klass       UPDATE with JDK8  The minimum requirements for proper codes are  lt pre  gt  and   code           test         lt pre gt   code     lt T gt  void test Class lt   super T gt  type           System out printf  hello  world n              lt  pre gt        yields    lt T gt  void test Class lt   super T gt  type         System out printf  hello  world n         And an optional surrounding  lt blockquote  gt  inserts an indentation          test         lt blockquote gt  lt pre gt   code     lt T gt  void test Class lt   super T gt  type           System out printf  hello  world n              lt  pre gt  lt  blockquote gt        yields        lt T gt  void test Class lt   super T gt  type             System out printf  hello  world n             Inserting  lt p gt  or surrounding with  lt p gt  and  lt  p gt  yields warnings

User · Answer

I work through these two ways without any problem   lt pre gt   lt code gt       java code  even including annotations  lt  code gt   lt  pre gt   and  lt pre class  quot code quot  gt       java code  even including annotations  lt  pre gt   Of course the latter is more simplest and observe the class  quot code quot  part

User · Answer

If you are Android developer you can use    lt pre class    prettyprint    gt   TODO your code    lt  pre gt    To pretty print your code in Javadoc with Java code

User · Answer

Here s my two cents   As the other answers already state  you should use  lt pre gt   lt  pre gt  in conjuction with   code     Use pre and   code    Wrapping your code inside  lt pre gt  and  lt  pre gt  prevents your code from collapsing onto one line  Wrapping your code inside   code   prevents  lt    gt  and everything in between from disappearing  This is particularly useful when your code contains generics or lambda expressions    Problems with annotations  Problems can arise when your code block contains an annotation  That is probably because when the   sign appears at the beginning of the Javadoc line  it is considered a Javadoc tag like  param or  return  For example  this code could be parsed incorrectly          Example usage         lt pre gt   code     Override    public void someOverriddenMethod       Above code will disappear completely in my case   To fix this  the line must not start with an   sign          Example usage         lt pre gt   code   Override    public int someMethod            return 13   37            lt  pre gt        Note that there are two spaces between  code and  Override  to keep things aligned with the next lines  In my case  using Apache Netbeans  it is rendered correctly

User · Answer

Using Java SE 1 6  it looks like all UPPERCASE PRE identifiers is the best way to do this in Javadoc           lt PRE gt     insert code as you would anywhere else     lt  PRE gt        is the simplest way to do this   An Example from a javadoc I got from a java awt Event method           lt PRE gt        int onmask   SHIFT DOWN MASK   BUTTON1 DOWN MASK        int offmask   CTRL DOWN MASK        if   event getModifiersEx    amp   onmask   offmask      onmask                              lt  PRE gt        This produces output that looks exactly like the regular code  with the regular code spacings and new lines intact

User · Answer

I just read the Javadoc 1 5 reference here  and only the code with  lt and  gt  must be enclosed inside   code       Here a simple example            Bla bla bla  for example         lt pre gt     void X           List  code  lt String gt   a                           lt  pre gt         param         return               your code then goes here

User · Answer

In addition to the already mentioned  lt pre gt  tags  you should also use the  code JavaDoc annotation  which will make life much easier when it comes to HTML entities issues  in particular with Generics   e g       lt pre gt      code   Set lt String gt  s    System out println s          lt  pre gt    Will give correct HTML output   Set lt String gt  s  System out println s     While omitting the  code block  or using a  lt code gt  tag  will result in HTML like this   Set s  System out println s      For reference  Java SE 8 tag descriptions can be found here  Javadoc Tags

User · Answer

You need the  lt pre gt  lt  pre gt  tags for the line breaks  and the   code       inside them for generics  But then it s not allowed to place the opening brace on the same line as the  lt generic gt  tag  because then everything will be displayed on 1 line again   Displays on one line           lt pre gt      code   public List lt Object gt  getObjects          return objects         lt  pre gt         Displays with line breaks           lt pre gt      code   public List lt Object gt  getObjects             return objects         lt  pre gt         Another weird thing is when you paste the closing brace of   code  it gets displayed           lt pre gt      code     public List lt Object gt  getObjects                return objects               lt  pre gt         Output   public List lt Object gt  getObjects         return objects

User · Answer

Try replacing  code  with  pre   The pre tag in HTML marks the text as preformatted and all linefeeds and spaces will appear exactly as you type them

User · Answer

I enclose my example code with  lt pre class  brush  java  gt  lt  pre gt  tags and use SyntaxHighlighter for published javadocs  It doesn t hurt IDE and makes published code examples beautiful

User · Answer

There is a significant difference between  lt blockquote gt  lt pre gt     and  lt pre gt   code     The former will omit the type declarations in generics but the latter will keep it   E g   List lt MyClass gt  myObject   null  displays as List myObject   null  with the firts and as List lt MyClass gt  myObject   null  with the second

User · Answer

I was able to generate good looking HTML files with the following snip-it shown in Code 1       lt pre gt       code    A-- gt B            C-- gt D                    G   E-- gt F         lt  pre gt     Code 1   Code 1 turned into the generated javadoc HTML page in Fig 1  as expected   A-- gt B      C-- gt D              G   E-- gt F    Fig  1   However  in NetBeans 7 2  if you hit Alt Shift F  to reformat the current file   Code 1 turns in to Code 2       lt     pre gt       code    A-- gt B            C-- gt D                    G   E-- gt F          lt  pre gt     Code 2   where the first  lt pre gt  is now broken onto two lines   Code 2 produces generated javadoc HTML file as shown in Fig 2    lt  pre gt  A-- gt B   C-- gt D     G E-- gt F    Fig 2   Steve B s suggestion  Code 3  seems to give the best results and remains formatted as expected even after hitting Alt Shift F     lt p gt  lt blockquote gt  lt pre gt             A-- gt B          C-- gt D                  G   E-- gt F    lt  pre gt  lt  blockquote gt     Code 3   Use of Code 3 produces the same javadoc HTML output as shown in Fig 1

[java] Multiple line code example in Javadoc comment

Examples related to java

Examples related to html

Examples related to javadoc