2

I have a Builder pattern in which I have a static class like as shown below:

public final class DataKey {

    private DataKey(Builder builder) {

    }

    public static class Builder {
        protected int maxCount = 3;

        // ..some other code here

        /**
         * This should be greater than 0 and less than equal to {@value Builder#maxCount}.
         * 
         * @param count
         * @throws IllegalArgumentException if count is less than 0 and greater than {@value Builder#maxCount}.
         * @return Builder object
         */         
        public Builder addCount(int count) {
            checkArgument(count > 0 && count < (maxCount + 1),
                    "maxCount should be greater than 0 and less than " + (maxCount + 1));
            this.maxCount = count;
            return this;
        }           
    }
}

Now I want to add a Javadoc on my addCount method so that I can show value of maxCount on it without hardcoding the actual number. I tried using {@value Builder#maxCount}, it doesn't show value 3 when I lookup the Javadoc on that method? What wrong I am doing here?

user1950349
  • 4,738
  • 19
  • 67
  • 119
  • The javadoc probably requires the variable to be `final`. maybe make a `protected static final int DEFAULT_MAX_COUNT = 3`? – Aarjav Jan 20 '16 at 01:06
  • I cannot set it as final because i am changing the value again in my addCount method. That 3 value is a default value I have put for that variable. – user1950349 Jan 20 '16 at 01:12
  • it does not make sense to have it for variable which change value as the program is running since the docs wont be changing. Thats why i suggested introducing a new static final variable. Then in the constructor you can do `this.maxCount = DEFAULT_MAX_COUNT;` – Aarjav Jan 20 '16 at 01:15
  • also as a side note, you may want to rename `addCount` as you're not actually adding to count. And you're using the same variable `maxCount` to check if the argument is within bounds. did you instead want to keep a second variable `count` such that `count <= maxCount` always? – Aarjav Jan 20 '16 at 01:22

2 Answers2

3
public static class Builder {
    protected static final int DEFAULT_MAX_COUNT = 3;
    /** count cannot be set to a value higher than this. By default, the value is {@value Builder#DEFAULT_MAX_COUNT}. */
    protected int maxCount = DEFAULT_MAX_COUNT;
    protected int count;

    // ..some other code here

    /**
     * This should be greater than 0 and less than equal to {@link Builder#maxCount}. By default,  {@value Builder#DEFAULT_MAX_COUNT}.
     * 
     * @param count
     * @throws IllegalArgumentException if count is less than 0 and greater than {@link Builder#maxCount}.
     * @return Builder object
     */         
    public Builder setCount(int count) {
        checkArgument(count > 0 && count < (maxCount + 1),
                "count should be greater than 0 and less than " + (maxCount + 1));
        this.count = count;
        return this;
    }

    /** ... */
    public Builder setMaxCount(int maxCount){
        checkArgument(count > 0, "maxCount must be greater than 0"); 
        this.maxCount = maxCount;
    }

    /** ... */
    public int getMaxCount(int maxCount){
         return this.maxCount;
    }

}

IMO, it does not make sense to have setters and getters for maxCount in Builder and should be a constant max instead (DEFAULT_MAX_COUNT).

The javadoc cannot show values of dynamic variables because the docs do not change as the program is running. javadoc is just text, there is no program running and therefore values can't be updated. Think of it as a manual (your javadoc) that comes with your alarm clock (the program). The manual can tell you all sorts of useful things and how to use the clock, but it can't tell you what the alarm is set to (as it'll never change). The {@value ..} stuff is like the clock's serial number. The person who is 'packaging' the clock knows the actual serial number and writes that out instead of .

ps. hope fully this is more along the lines of what you're actually looking for:

public static class Builder {
    protected static final int MAX_MAX_COUNT = 3;
    /** By default, the value is {@value Builder#MAX_MAX_COUNT}. */
    protected int maxCount = MAX_MAX_COUNT;

    // ..some other code here

    /**
     * This should be greater than 0 and less than equal to {@value Builder#MAX_MAX_COUNT}.
     * 
     * @param maxCount
     * @throws IllegalArgumentException if maxCount is less than 0 and greater than {@link Builder#MAX_MAX_COUNT}.
     * @return Builder object
     */         
    public Builder setMaxCount(int maxCount) {
        checkArgument(maxCount > 0 && maxCount < (MAX_MAX_COUNT + 1),
                "count should be greater than 0 and less than " + (MAX_MAX_COUNT + 1));
        this.maxCount = maxCount;
        return this;
    }
}
Aarjav
  • 1,334
  • 11
  • 22
  • Thanks Aarjav for the suggestion. If I take mouse over `setMaxCount` method, I don't see value 3 as being resolved. Instead I see like this as it is `less than equal to {@value Builder#MAX_MAX_COUNT}.` – user1950349 Jan 20 '16 at 02:25
  • I just tried it and it seems to be working for me, what does your `MAX_MAX_COUNT` declaration look like? does your IDE autocomplete in `{@value }` blocks for you? if so, see if `Buil` gets autocompleted or `Builder#MAX_MAX` – Aarjav Jan 20 '16 at 02:35
  • I exactly copied as it is. I don't see `{@value Builder#MAX_MAX_COUNT}` getting resolved to 3 while hovering the mouse over `maxCount` variable or `setMaxCount` method after saving the file. – user1950349 Jan 20 '16 at 02:51
  • can you check to see if `{@link Builder#MAX_MAX_COUNT}` gets resolved? – Aarjav Jan 20 '16 at 02:56
  • Oh it maybe something to do with your javadoc visibility level http://stackoverflow.com/questions/11426959/javadoc-displaying-value-on-an-inner-class-constant-using-value . In my env I have it set to show doc for private and all. – Aarjav Jan 20 '16 at 03:00
  • How do I make this change in my eclipse? – user1950349 Jan 20 '16 at 03:46
  • Does generating it manually once fix it? http://stackoverflow.com/questions/4468669/how-to-generate-javadoc-html-in-eclipse I don't use eclipse so I'm not familiar with it – Aarjav Jan 20 '16 at 04:35
1

You can only do this for constants. It will work when you make the variable static final.

Maarten Brak
  • 816
  • 1
  • 7
  • 10