Win a copy of TensorFlow 2.0 in Action this week in the Artificial Intelligence and Machine Learning forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
  • Campbell Ritchie
  • Liutauras Vilda
  • Paul Clapham
  • Bear Bibeault
  • Jeanne Boyarsky
  • Ron McLeod
  • Tim Cooke
  • Devaka Cooray
Saloon Keepers:
  • Tim Moores
  • Tim Holloway
  • Jj Roberts
  • Stephan van Hulst
  • Carey Brown
  • salvin francis
  • Scott Selikoff
  • fred rosenberger

JavaDoc include private?

Ranch Hand
Posts: 213
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hey guys,
Are you submitting your javadocs showing private members and methods or just public?
Ranch Hand
Posts: 96
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In my assignment they asked for the public interface only...
but dont be lazy and javadoc everything...
Posts: 3252
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I would suggest javadoccing everything, but not necessarily generating javadoc documentation for everything.
The first question you should be asking yourself is: who is the audience for these javadocs? My assumption was at the time that the primary audience for the javadocs are developers writing new code against your classes.
Generating Javadocs for public methods only is a bad idea. Why? Unless you make your classes final, developers can create subclasses of your classes and gain access to protected methods. So your minimum documentation level should be for public and protected methods.
Given the audience assumption above, generating Javadocs for all methods, including private ones, is also a bad idea. Why? Because external code can't get at private methods anyway. Documenting them introduces a lot of unnecessary information into the docs that only serves to clutter up and confuse. Private methods are only interesting for developers working on the class itself, and they already have the source code including the javadocs in front of them; if that's not enough for them, they should be capable enough to generate full docs themselves.
This leaves the decision whether to include package-private methods or not. This depends on whether you think your audience will be developing further classes in the same package(s) or not.
- Peter
    Bookmark Topic Watch Topic
  • New Topic