0

When I want to known how to use some class, I look at its Javadoc. For instance, consider LocalTime. I only see documentation for static fields of that class, MAX, and so on. I don't see fields that I'd expect it to have, such as second and nano, based on there being methods like int getSecond() and int getNano(). Why aren't these fields documented? Why can I only learn about them by reading the source?

5
  • 10
    In general, API documentation is concerned only with the API -- the "I" stands for "Interface". Private fields, like the ones you cited, are not part of the interface of the class, they are internal details that should not be relied on by clients of the class. So they are not documented, and as they depend on the specific implementation, the source code for that implementation is the authoritative way to find information about them. Commented Mar 24, 2023 at 2:49
  • 2
    As aptly pointed out already, they aren't documented because they aren't part of the public API (if they exist at all). You don't actually need to know about a possible second field in LocalTime in order to understand how to use LocalTime. That said, if you're interested in the implementation, you can always look at the source code on GitHub or in the src.zip file included with your JDK (which is typically easiest via your IDE of choice).
    – Slaw
    Commented Mar 24, 2023 at 3:02
  • 2
    My professor used class Thermometer as an example. It might have public double getFahrenheit () and public double getCelsius (), but internally have the temperature in Kelvin. Commented Mar 24, 2023 at 3:37
  • 1
    Start by reading about encapsulation and data protection. It’s general for all programming languages and libraries that they hide the fields (instance variables) and only document the methods, even only some of them since other methods may also be hidden or private. It’s the same all over the Java standard library too. There are only a few exceptions where protected fields that may be used by your own subclasses are documented. You may find the source code and see what fields there are, butr (1) you have no good use for that information anyway (2) they may not exist in the next Java version.
    – Anonymous
    Commented Mar 24, 2023 at 8:11
  • 1
    Closely related: Java Doc - Do fields also get documented? on StackExchange Software Engineering.
    – Anonymous
    Commented Mar 24, 2023 at 8:13

2 Answers 2

5

You don't actually know whether it has a second or nano field, though. Just because it has methods like int getMinute() doesn't mean that there's an int minute field. Part of encapsulation is that you interact with the classes though their public API (which is documented) rather than through implementation details.

I could implement that int getMinute() method like:

class LocalTime {
  private int negativeMinutes;

  // ...

  public int getMinutes() {
    return -1 * negativeMinutes;
  }
}

or by

class LocalTime {
  private String minutes;

  // ...

  public int getMinutes() {
    return Integer.valueOf(minutes);
  }
}

and those could both be conforming implementations. They wouldn't be great implementations, but they'd have the same public API. The point of the public documentation is that you don't need to know the implementation details.

Now, if you're generating Javadoc for your own code, you can actually instruct Javadoc to generate documentation for fields with lower levels of visibility, like private fields and methods. Those aren't all that useful for most users, though, since they probably won't be able to call those methods or access those fields, unless they use some reflective methods.

As to source of LocalTime, there are open source Java implementations, and you'd be able to look at the source there.

2

Java doc is to document public fields and methods. As these fields are private, they are not documented. As user cannot access private fields or method, they are generally not included in java doc.

There are getter methods for these fields which you can find the java doc. Java doc is to help user to find the public method/fields for their use-cases. Hence, you are not finding nano and second in the java doc.

Not the answer you're looking for? Browse other questions tagged or ask your own question.