We Keep Coding

Porting parseUnsignedInt to java1.7

I was using java1.8 which has parseUnsignedInt(). I was told that we have to use java1.7 since that is on the system. I thought I could just port the java.lang.Interger.java, java.lang.Long.java and java.lang.annotation.Native.java functions and compile with my code. This allowed the code to compile without errors. When I run I get the following error:
Exception in thread "Thread-6" java.lang.NoSuchMethodError: java.lang.Integer.parseUnsignedInt(Ljava/lang/String;)I
The eclipse debugger can't seem to find the function either. What do I have to do to get this working?

The method parseUnsignedInt was introduced with Java 1.8, as it is documented in its javadoc (mind the #since 1.8):
/**
* Parses the string argument as an unsigned decimal integer. The
* characters in the string must all be decimal digits, except
* that the first character may be an an ASCII plus sign {#code
* '+'} ({#code '\u005Cu002B'}). The resulting integer value
* is returned, exactly as if the argument and the radix 10 were
* given as arguments to the {#link
* #parseUnsignedInt(java.lang.String, int)} method.
*
* #param s a {#code String} containing the unsigned {#code int}
* representation to be parsed
* #return the unsigned integer value represented by the argument in decimal.
* #throws NumberFormatException if the string does not contain a
* parsable unsigned integer.
* #since 1.8
*/
public static int parseUnsignedInt(String s) throws NumberFormatException {
return parseUnsignedInt(s, 10);
}
But the JDK also contains the sources, so you could write your own parseUnsignedInt method in your own class, similar to the implementation contained in Java 8 if the Java 8 license allows that.
See http://hg.openjdk.java.net/jdk8/jdk8/jdk/file/687fd7c7986d/src/share/classes/java/lang/Integer.java
Line 661 ff
For details about security (i.e. why you can't place your own Integer class in java.lang package), option to overrule this security, and a reason why you should not (or better - why you are not allowed to), see selected answer in Why I am able to re-create java.lang package and classes?
So, you will have to implement your own class in your own package:
package com.yourname;
/*
* Contains code from OpenJDK Java8, Copyright (c) 1994, 2013, Oracle and/or its affiliates.
* TODO add more info from Oracle class comment here.
*/
public class IntCompatUtilities {
public static int parseUnsignedInt(String s) throws NumberFormatException {
return parseUnsignedInt(s,10);
}
public static int parseUnsignedInt(String s, int radix)
throws NumberFormatException {
//TODO content from OpenJDK 8's Integer.parseUnsignedInt(String,int) here.
//instead of return parseInt(s, radix); change to return Integer.parseInt(s, radix);
//instead of throw NumberFormatException.forInputString(s); throw new NumberFormatException(...)
}
}
And then, let all your callers call com.yourname.IntCompatUtilities.parseUnsignedInt(...)

How to format javadoc in intelliJ [duplicate]

I have a small code example I want to include in the Javadoc comment for a method.
/**
* -- ex: looping through List of Map objects --
* <code>
* 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"));
* }
* </code>
*
* #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 ?

In addition to the already mentioned <pre> 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.:
* <pre>
* {#code
* Set<String> s;
* System.out.println(s);
* }
* </pre>
Will give correct HTML output:
Set<String> s;
System.out.println(s);
While omitting the #code block (or using a <code> tag) will result in HTML like this:
Set s;
System.out.println(s);
For reference, a full list of tag descriptions available in Java SE 8 can be found here.

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 <code> - 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.
* <pre>
* <code>new BeanTranslator.Builder()
* .translate(
* new{#code Translator<String, Integer>}(String.class, Integer.class){
* {#literal #}Override
* public Integer translate(String instance) {
* return Integer.valueOf(instance);
* }})
* .build();
* </code>
* </pre>
* #param translator
*/
gets printed as
new BeanTranslator.Builder()
.translate(
new Translator<String, Integer>(String.class, Integer.class){
#Override
public Integer translate(String instance) {
return Integer.valueOf(instance);
}})
.build();

The java source has lots of good examples for this. Here's an example from the head of "String.java":
....
* is equivalent to:
* <p><blockquote><pre>
* char data[] = {'a', 'b', 'c'};
* String str = new String(data);
* </pre></blockquote><p>
* Here are some more examples of how strings can be used:
* <p><blockquote><pre>
* System.out.println("abc");
* String cde = "cde";
* System.out.println("abc" + cde);
* String c = "abc".substring(2,3);
* String d = cde.substring(1, 2);
* </pre></blockquote>
...

Enclose your multiline code with <pre></pre> tags.

You need the <pre></pre> 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 <generic> tag, because then everything will be displayed on 1 line again.
Displays on one line:
* ..
* <pre>
* {#code
* public List<Object> getObjects() {
* return objects;
* }
* </pre>
* ..
Displays with line breaks:
* ..
* <pre>
* {#code
* public List<Object> getObjects()
* {
* return objects;
* }
* </pre>
* ..
Another weird thing is when you paste the closing brace of {#code, it gets displayed:
* ..
* <pre>
* {#code
* public List<Object> getObjects()
* {
* return objects;
* }
* }
* </pre>
* ..
Output:
public List<Object> getObjects()
{
return objects;
}
}

/**
* <blockquote><pre>
* {#code
* public Foo(final Class<?> klass) {
* super();
* this.klass = klass;
* }
* }
* </pre></blockquote>
**/
<pre/> is required for preserving lines.
{#code must has its own line
<blockquote/> is just for indentation.
public Foo(final Class<?> klass) {
super();
this.klass = klass;
}
UPDATE with JDK8
The minimum requirements for proper codes are <pre/> and {#code}.
/**
* test.
*
* <pre>{#code
* <T> void test(Class<? super T> type) {
* System.out.printf("hello, world\n");
* }
* }</pre>
*/
yields
<T> void test(Class<? super T> type) {
System.out.printf("hello, world\n");
}
And an optional surrounding <blockquote/> inserts an indentation.
/**
* test.
*
* <blockquote><pre>{#code
* <T> void test(Class<? super T> type) {
* System.out.printf("hello, world\n");
* }
* }</pre></blockquote>
*/
yields
<T> void test(Class<? super T> type) {
System.out.printf("hello, world\n");
}
Inserting <p> or surrounding with <p> and </p> yields warnings.

Here's my two cents.
As the other answers already state, you should use <pre> </pre> in conjuction with {#code }.
Use pre and {#code}
Wrapping your code inside <pre> and </pre> prevents your code from collapsing onto one line;
Wrapping your code inside {#code } prevents <, > 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:
*
* <pre>{#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:
*
* <pre>{#code #Override
* public int someMethod() {
* return 13 + 37;
* }
* }</pre>
*/
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.

I was able to generate good looking HTML files with the following snip-it shown in Code 1.
* <pre>
* {#code
* A-->B
* \
* C-->D
* \ \
* G E-->F
* }
*</pre>
(Code 1)
Code 1 turned into the generated javadoc HTML page in Fig 1, as expected.
A-->B
\
C-->D
\ \
G E-->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.
* <
* pre>
* {#code
* A-->B
* \
* C-->D
* \ \
* G E-->F
* }
* </pre>
(Code 2)
where the first <pre> is now broken onto two lines. Code 2 produces generated javadoc HTML file as shown in Fig 2.
< pre> A-->B \ C-->D \ \ G E-->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.
*<p><blockquote><pre>
* A-->B
* \
* C-->D
* \ \
* G E-->F
* </pre></blockquote>
(Code 3)
Use of Code 3 produces the same javadoc HTML output as shown in Fig 1.

Since Java 18 (JEP 413) you may use #snippet tag:
/**
* -- ex: looping through List of Map objects --
* {#snippet :
* 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"));
* }
* }
*
* #param query - select statement
* #return List of Map objects
*/

There is a significant difference between <blockquote><pre>... and <pre>{#code.... The former will omit the type declarations in generics but the latter will keep it.
E.g.:
List<MyClass> myObject = null;
displays as List myObject = null; with the firts and as List<MyClass> myObject = null; with the second

I just read the Javadoc 1.5 reference here, and only the code with <and > must be enclosed inside {#code ...}. Here a simple example:
/**
* Bla bla bla, for example:
*
* <pre>
* void X() {
* List{#code <String>} a = ...;
* ...
* }
* </pre>
*
* #param ...
* #return ...
*/
.... your code then goes here ...

A combination of two of the other solutions seems perfect:
* <pre>{#code
* {#literal #}Override
* public void someMethod() {
* Set<String> s;
* }
* }</pre>
ie. use <pre>{#code to start and }</pre> to end the snippet. Also, replace # with {#literal #}.
Haven't found an easier solution. Quite sad for a language that has been under active development for decades.

If you are Android developer you can use:
<pre class=”prettyprint”>
TODO:your code.
</pre>
To pretty print your code in Javadoc with Java code.

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.

I work through these two ways without any problem:
<pre>
<code>
... java code, even including annotations
</code>
</pre>
and
<pre class="code">
... java code, even including annotations
</pre>
Of course the latter is more simplest and observe the class="code" part

I enclose my example code with <pre class="brush: java"></pre> tags and use SyntaxHighlighter for published javadocs. It doesn't hurt IDE and makes published code examples beautiful.

Using Java SE 1.6, it looks like all UPPERCASE PRE identifiers is the best way to do this in Javadoc:
/**
* <PRE>
* insert code as you would anywhere else
* </PRE>
*/
is the simplest way to do this.
An Example from a javadoc I got from a java.awt.Event method:
/**
* <PRE>
* int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
* int offmask = CTRL_DOWN_MASK;
* if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
* ...
* }
* </PRE>
*/
This produces output that looks exactly like the regular code, with the regular code spacings and new lines intact.

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.
``` */

Customize Javadoc template in Android Studio

When I type "/** + Enter" above a method in Android Studio, it automatically generates this Javadoc for me.
/**
*
* #param xInt
* #param xString
* #param xBoolean
* #return
*/
public static String someMethod(int xInt, String xString, boolean xBoolean) {
if (xString == Integer.toString(xInt) == xBoolean) {
return "all are equal";
}
return "a string";
}
I want to change the JavaDoc template, so that when I type "/** + Enter", it will automatically generate this:
/**
* Explanation of Method here
*
* #param xInt Interger Explanation here
* #param xString String Explanation here
* #param xBoolean Boolean Explanation here
* #return Explanation Here
*/

I don't think it is possible to customize the JavaDocs template. This is done automatically by Android Studio based on the method signature.

Javadoc #param with -

I'm making javadoc:
/**
* make Something
*
* #param value - blabla( I´m using #param value - blabla, instead #param
* value blabla)
* #return something
*/
public String makeSomething(String value) {
return "";
}
Should I use #param value - or just #param value?

Most doclets introduce a hypen between the #param tag and the parameter's name. Adding another hypen yourself will cause an ugly, double hypen to be rendered.

Multiple line code example in Javadoc comment

I have a small code example I want to include in the Javadoc comment for a method.
/**
* -- ex: looping through List of Map objects --
* <code>
* 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"));
* }
* </code>
*
* #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 ?

In addition to the already mentioned <pre> 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.:
* <pre>
* {#code
* Set<String> s;
* System.out.println(s);
* }
* </pre>
Will give correct HTML output:
Set<String> s;
System.out.println(s);
While omitting the #code block (or using a <code> tag) will result in HTML like this:
Set s;
System.out.println(s);
For reference, a full list of tag descriptions available in Java SE 8 can be found here.

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 <code> - 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.
* <pre>
* <code>new BeanTranslator.Builder()
* .translate(
* new{#code Translator<String, Integer>}(String.class, Integer.class){
* {#literal #}Override
* public Integer translate(String instance) {
* return Integer.valueOf(instance);
* }})
* .build();
* </code>
* </pre>
* #param translator
*/
gets printed as
new BeanTranslator.Builder()
.translate(
new Translator<String, Integer>(String.class, Integer.class){
#Override
public Integer translate(String instance) {
return Integer.valueOf(instance);
}})
.build();

The java source has lots of good examples for this. Here's an example from the head of "String.java":
....
* is equivalent to:
* <p><blockquote><pre>
* char data[] = {'a', 'b', 'c'};
* String str = new String(data);
* </pre></blockquote><p>
* Here are some more examples of how strings can be used:
* <p><blockquote><pre>
* System.out.println("abc");
* String cde = "cde";
* System.out.println("abc" + cde);
* String c = "abc".substring(2,3);
* String d = cde.substring(1, 2);
* </pre></blockquote>
...

Enclose your multiline code with <pre></pre> tags.

You need the <pre></pre> 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 <generic> tag, because then everything will be displayed on 1 line again.
Displays on one line:
* ..
* <pre>
* {#code
* public List<Object> getObjects() {
* return objects;
* }
* </pre>
* ..
Displays with line breaks:
* ..
* <pre>
* {#code
* public List<Object> getObjects()
* {
* return objects;
* }
* </pre>
* ..
Another weird thing is when you paste the closing brace of {#code, it gets displayed:
* ..
* <pre>
* {#code
* public List<Object> getObjects()
* {
* return objects;
* }
* }
* </pre>
* ..
Output:
public List<Object> getObjects()
{
return objects;
}
}

/**
* <blockquote><pre>
* {#code
* public Foo(final Class<?> klass) {
* super();
* this.klass = klass;
* }
* }
* </pre></blockquote>
**/
<pre/> is required for preserving lines.
{#code must has its own line
<blockquote/> is just for indentation.
public Foo(final Class<?> klass) {
super();
this.klass = klass;
}
UPDATE with JDK8
The minimum requirements for proper codes are <pre/> and {#code}.
/**
* test.
*
* <pre>{#code
* <T> void test(Class<? super T> type) {
* System.out.printf("hello, world\n");
* }
* }</pre>
*/
yields
<T> void test(Class<? super T> type) {
System.out.printf("hello, world\n");
}
And an optional surrounding <blockquote/> inserts an indentation.
/**
* test.
*
* <blockquote><pre>{#code
* <T> void test(Class<? super T> type) {
* System.out.printf("hello, world\n");
* }
* }</pre></blockquote>
*/
yields
<T> void test(Class<? super T> type) {
System.out.printf("hello, world\n");
}
Inserting <p> or surrounding with <p> and </p> yields warnings.

Here's my two cents.
As the other answers already state, you should use <pre> </pre> in conjuction with {#code }.
Use pre and {#code}
Wrapping your code inside <pre> and </pre> prevents your code from collapsing onto one line;
Wrapping your code inside {#code } prevents <, > 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:
*
* <pre>{#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:
*
* <pre>{#code #Override
* public int someMethod() {
* return 13 + 37;
* }
* }</pre>
*/
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.

I was able to generate good looking HTML files with the following snip-it shown in Code 1.
* <pre>
* {#code
* A-->B
* \
* C-->D
* \ \
* G E-->F
* }
*</pre>
(Code 1)
Code 1 turned into the generated javadoc HTML page in Fig 1, as expected.
A-->B
\
C-->D
\ \
G E-->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.
* <
* pre>
* {#code
* A-->B
* \
* C-->D
* \ \
* G E-->F
* }
* </pre>
(Code 2)
where the first <pre> is now broken onto two lines. Code 2 produces generated javadoc HTML file as shown in Fig 2.
< pre> A-->B \ C-->D \ \ G E-->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.
*<p><blockquote><pre>
* A-->B
* \
* C-->D
* \ \
* G E-->F
* </pre></blockquote>
(Code 3)
Use of Code 3 produces the same javadoc HTML output as shown in Fig 1.

Since Java 18 (JEP 413) you may use #snippet tag:
/**
* -- ex: looping through List of Map objects --
* {#snippet :
* 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"));
* }
* }
*
* #param query - select statement
* #return List of Map objects
*/

There is a significant difference between <blockquote><pre>... and <pre>{#code.... The former will omit the type declarations in generics but the latter will keep it.
E.g.:
List<MyClass> myObject = null;
displays as List myObject = null; with the firts and as List<MyClass> myObject = null; with the second

I just read the Javadoc 1.5 reference here, and only the code with <and > must be enclosed inside {#code ...}. Here a simple example:
/**
* Bla bla bla, for example:
*
* <pre>
* void X() {
* List{#code <String>} a = ...;
* ...
* }
* </pre>
*
* #param ...
* #return ...
*/
.... your code then goes here ...

A combination of two of the other solutions seems perfect:
* <pre>{#code
* {#literal #}Override
* public void someMethod() {
* Set<String> s;
* }
* }</pre>
ie. use <pre>{#code to start and }</pre> to end the snippet. Also, replace # with {#literal #}.
Haven't found an easier solution. Quite sad for a language that has been under active development for decades.

If you are Android developer you can use:
<pre class=”prettyprint”>
TODO:your code.
</pre>
To pretty print your code in Javadoc with Java code.

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.

I work through these two ways without any problem:
<pre>
<code>
... java code, even including annotations
</code>
</pre>
and
<pre class="code">
... java code, even including annotations
</pre>
Of course the latter is more simplest and observe the class="code" part

I enclose my example code with <pre class="brush: java"></pre> tags and use SyntaxHighlighter for published javadocs. It doesn't hurt IDE and makes published code examples beautiful.

Using Java SE 1.6, it looks like all UPPERCASE PRE identifiers is the best way to do this in Javadoc:
/**
* <PRE>
* insert code as you would anywhere else
* </PRE>
*/
is the simplest way to do this.
An Example from a javadoc I got from a java.awt.Event method:
/**
* <PRE>
* int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
* int offmask = CTRL_DOWN_MASK;
* if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
* ...
* }
* </PRE>
*/
This produces output that looks exactly like the regular code, with the regular code spacings and new lines intact.

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.
``` */