I'm wondering what portion of Java developers actually invest in writing package.html files, and what they write in them. I am particularly interested in packages that can serve as your public APIs.
In addition, I'm wondering whether developers actually bother to read the package level documentation when they use unfamiliar APIs, and whether they only investigate the "subject line" or the rest of the text.
I realize this is a subjective question, but it is for research purposes.
I typically access an API at the class level, and read the details only on the specific methods I have questions about. Adding information on the package's general purpose is good practice, but I would venture to guess that most will not see the information.
No, I essentially never write them at this point. I used to in my early days as a developer. And there is probably a reason for that.
In the early stages of learning Java, I recall using package level docs a lot. Some of the Sun ones were useful for helping me find where things were, back in the time when I knew nothing about Java (and little about programming).
But I honestly can't remember the last time that I've used them with Sun's documentation, and with other products, I've found them universally useless.
I wrote lots of package-level documentation at my last job. Some packages contain lots of different stuff that may be hard to understand when you only look at it at the class-level. I wrote a package to send GSM messages to serial port modems, and while the single classes were all rather easy to understand because they didn’t do much the package as a whole was a lot more complicated (with Modems, ModemConnectors, Drivers, Transports and what not). In those instances a package-level javadoc comment that explains how it all fits together has its worth.