Acces private field from doc comment in java

user_11984428 0
Viewed 109

Given the following class:

public class A {
    private Boolean attribute;
     
    public Boolean getAttribute () {
        return this.attribute; 
    }    
    
    public Boolean setAttribute (Boolean b) {
        this.attribute = b; 
    }
}

How could I access the private field from class A, from a documentation comment in another class, in the following manner, in order to specify that this field is changed at some point in the documented method, even if is not directly accessed?

public class B {
    /**
     * This method turns the {@link A#attribute} attribute to false.
     */
    public turnOffField (A a) {
        //...
    }
}

The above {@link A#attribute} is just a representation, since, as you would imagine, it doesnt work.

NOTE: In my case the documentation comments are not aimed to generate javadocs pages, instead they are meanted to serve as inside documentation, only for developers to consume. So command-line's options like -produce doesnt fill the purpouse in this case.

spring-boot javadoc documentation private java
1 Answers

Javadoc pages are meant to be consumed by, and only by, developers. Also, always remember that you can communicate with future developers through basic comments, too. After all, javadoc is only a special form of comment.

In this particular use case, I recommend revising the form of developer documentation.

Let us have an example and since I like copying from big frameworks, let it be Java

LinkedList<String> list = new LinkedList<>();
list.add("Hello");
list.add("World");

and let us look at the second invocation of the add method. Internally, this method creates a new LinkedList.Node wrapper and sets the list's internal tail member to that wrapper (and does some other stuff).

Do we actually care about these details? I suppose that's very rare and in most occasions the only thing we are interested in is that "World" gets added to the list, whatever the implementation has to do to accomplish that.

To properly document the example given in the question in the same manner, we would need to know how attribute affects the behavior of A. Let us say it controls some tracing, then we could document

class A {

    private boolean attribute;

    /**
     * Controls tracing of this instance.
     */
    public boolean setAttribute(boolean attribute) {
        this.attribute = attribute;
    }

}

and

class B {

    /**
     * Turns of tracing for the specified instance of {@code A}.
     * @see A#setAttribute
     */
    public void turnOffTracing(A a) {
        a.setAttribute(false);
    }

}

Generally, you should not need to refer to internal members in order to describe how your class or method is working. That would break the basic idea of a private field, since its contract is somewhat not private anymore - if you change the field, the documentation of your class would need to change, too, thus some clients might want to change their code as well.

Of course in this example it is also a good idea to rename setAttribute, but that does not affect the wording of the documentation.

user_75251320
Related