Search code examples
javajavadoc

Javadoc value of static byte in hex form

I have some static final byte fields in a class:

public static final byte    TOP_LEFT_SIGNAL     = 0x0F;
public static final byte    TOP_CENTER_SIGNAL   = 0x1F;
public static final byte    TOP_RIGHT_SIGNAL    = 0x3F;

and I'm writing documentation for some class methods, like so:

/**
 * Takes a signal byte and returns an encoded message (byte array).
 * <p>
 * Example:
 * <pre>
 * Input - {@value #TOP_LEFT_SIGNAL} (TOP_LEFT_SIGNAL)
 *
 * Output - [0x00, 0x0F, 0x52, 0x53]
 * </pre>
 *
 * @param b
 *            - signal byte.
 * @return an encoded message (byte array).
 */
public static final byte[] encodeMsg(byte b) {
    return addTail(b);
}

The above documentation outputs the Input - {@value #TOP_LEFT_SIGNAL} (TOP_LEFT_SIGNAL) line like so:

Input - 15 (TOP_LEFT_SIGNAL)   // 15 is underlined and linked to the static variable


My two questions:

  1. Is there a way to output the static value in hexadecimal format with a leading 0x (0x0F instead of 15)? Something like, Input - {@value Integer#toHexString(Foo#TOP_LEFT_SIGNAL)}

  2. Can I make it so that the value (15 in this example) is not underlined and not linked to the static field, while still using the value of the static field?

Are either of my questions possible?

Reasoning:

I'm currently putting the literal byte values (0x0F) in the documentation. The reason why I want to automate this is because this is a utility class that I have already written the methods for and some of the constants. As I write the core classes that make use of this utility class I find myself needing to add constants but not change the methods. The constants are separated into different byte blocks, like 0x40 - 0x4F and larger values are meant to carry a heavier meaning. Thus when I insert a new constant that carries a lesser weight than another constant, I insert the constant and shift the other constant values up. This makes me need to update every example in every method's documentation.

Workaround to the first question:

I know I could use the following workaround to answer the first question.

public static final String    TOP_LEFT_SIGNAL    = "0x0F";

/**
 * Input - {@value #TOP_LEFT_SIGNAL} (TOP_LEFT_SIGNAL)
 */
public static final byte[] encodeMsg(String b) {
    return addTail(Byte.decode(b));
}

But I'd rather not use Byte.decode(String nm) whenever I need the byte value of a static field.

Solution

  • Since your values are constant, maybe you can use {@literal literal_text}.

    Or you can create your own custom Javadoc tags through a class extending Doclet, as described in the Doclet documentation.