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?
2 Answers
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.
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.
second
field inLocalTime
in order to understand how to useLocalTime
. That said, if you're interested in the implementation, you can always look at the source code on GitHub or in thesrc.zip
file included with your JDK (which is typically easiest via your IDE of choice).class Thermometer
as an example. It might havepublic double getFahrenheit ()
andpublic double getCelsius ()
, but internally have the temperature in Kelvin.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.