I've been writing Java for a while, using eclipse.
Generally, I have a src folder, and put sub folders under src and then put the classes in the sub folders.
So, I don't really use packages, and don't know what packages are used for
Now, when I generate the javadoc, the package/class layout doesn't make sense to me.
How should I layout the folders / packages / classes so that the javadoc organization makes sense.
Generally, I have one target executable for a project. Except that I make a large number of development classes that also execute. The projects have a number of classes that should be organized, possibly into packages, like gui, solver, network, dataobject(s). Also, I make some unit tests and put those classes in test/sub_directory, similar to src/sub_directory. The developmental classes are in development/sub_directory, but the development sub_directory names are associated with the developmental goal, and the sub directory names are different than test and src.
Also, are there any additional files that should be created that would assist javadoc? Like a project description?
I do something similar using NetBeans. I am by no means an expert and what I'm offering is a discussion not a recommendation.
I use packages within a project the same way I do a separate class library projects, as an organizational and encapsulation process. Now where to draw the line between a separate package and separate library is kind of fuzzy. It often becomes much more clear during refactoring sessions with the benefit of hind sight in how the classes are used, what they depend on, and the chances of reuse in other projects.
Writing good javadoc is a lot like any good writing. The tricks I've learned are:
Read other peoples' javadoc with a critical eye for what you like and what you don't
Consider your audience, they are people digging into your code but are they maintaining or reusing?
The real hard part is to be informative without including unnecessary details that risk code and documentation conflicts
Use the javadoc, and fix it instead of cursing it
I've seen too many descriptions that are redundant such as int getDoDah() "return the current value of DoDah", when what I really want to know is what the heck is a DoDah.
On the other end I've also seen boolean checkValue(int it) "returns true if it is less than 10" and the code looks like "return it<5;"
NetBeans presents the javadoc while typing and I'm pretty sure Eclipse does too. I use it most to make sure my method parameters are correct. So I try to read it almost every time and if I have to go to the code to answer a question, that's the perfect time to update the javadoc.
Now generating the whole javadoc for a project and reading it from the perspective of the person you're going to send it to, helps a lot. But I find the details are used much more than the overviews.
To address your question how to organize your project into packages so the documentation is more understandable, I think it is a design exercise as much as a documentation chore. I do it as an iterative process but I'm very much into the minimal design, rapid prototype development, and endless refinement paradigm. I tend to end up with a prototype with one package then divide it into UI, database, network, non-interactive processing for example. Sometimes that's a lot of work if the prototype is severely criticized. But just as often I get to throw out big chunks of the prototype because I was just plain wrong about what I thought people would do with it. That's easier if there's not a big investment of time and energy in each Class and method.
After rereading that, it sure is a bunch of general jibber jabber. Hope some of it makes sense.
It's not what your program can do, it's what your users do with the program.
I am a bit surprised that you don’t have your classes in packages. The javadoc tool does not require any particular package structure that I know about, but you ought to be putting your files in packages. In fact, Eclipse usually complains if you don’t use package names.
I am not quite sure I have understood your problem, but I presume you have seen the Javadoc style guide, and a link I found on Google about package descriptions.
Joined: Oct 13, 2005
You can set a preference in your IDE that public members of classes must have documentation comments, or similar. Then you will get a yellow warning if you forget the comments. You write /**-enter, just before a completed member and you get a skeleton comment.