CODEWITHSUNDEEP
javajavadocbuilderbuilder-pattern
user1950349
user1950349

Reputation: 5146

how to show the value of a variable in javadoc on a method?

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?

Upvotes: 2

Views: 7550

Answers (2)

Aarjav
Aarjav

Reputation: 1374

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;
    }
}

Upvotes: 3

Maarten Brak
Maarten Brak

Reputation: 891

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

Upvotes: 1

Related Questions