Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

The standard JavaDoc template(Doclet) didn't change much until the recent JDK7. In my opinion, JDK7 template only made it even more difficult to browse. I looked at several third-party doclets, but none is what I want. So I started to design a new open source JavaDoc template from scratch to improve the usability. Here's something I thought about,

  • Searching. It should be done at client side to make it working on your local file system.
  • IDE-like interactive navigation. The standard JavaDoc uses two frames to show packages and classes separately, which is far less usable than an Eclipse-like navigator. What made it even worse is that if you clicked inside the right side frame, the package index and class index will not refresh accordingly. You have no idea where you are.
  • URLs. One drawback of the frames is that the URL do not change according to the frames. It's very frustrating that you can't send a JavaDoc URL to someone unless you explicitly check the URL of the individual frame.
  • Look and feel. You don't need to be a designer to see JavaDoc is ugly. I want to make JavaDoc better and I want to make sure I do it right. The question for you to answer is,

What you expect a better JavaDoc should be?

share|improve this question

closed as not constructive by GlenH7, Walter, gnat, ChrisF Oct 24 '12 at 14:29

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.If this question can be reworded to fit the rules in the help center, please edit the question.

I use this Userscript to get at least searching (and copying-a-specific-URL) easily from every JavaDoc (local and on the web). I'm sure you can easily modify it to be built-in to your JavaDoc. – Joachim Sauer Oct 24 '12 at 13:00
Actually, the standard doclet uses frames and not iframes which is a lot worse. – Ingo Kegel Oct 24 '12 at 13:02
@IngoKegel Thank you. Corrected. – chemhack Oct 24 '12 at 13:05
I would expect it not forcing me to re-learn and re-memorize things I learned and memorized with "old bad" javadoc – gnat Oct 24 '12 at 13:16
While subjective questions are allowed, I don't see how this question is anything more than a list style question. What references could be cited in order to verify an answer as correct? Please consider rephrasing your question to make it more on-topic for P.SE per the faq. – GlenH7 Oct 24 '12 at 13:26

This isn't answering your question directly, but since you're keen to make a difference :-).

I'd contact Jonathon Gibbons on the compiler project in OpenJDK - he's looking for people to help overhaul the Javadoc system and to provide the sorts of features you're talking about. It means your changes would go into Java itself!

Alternatively come and join the Adopt OpenJDK project and we'll get you started.

share|improve this answer
What I'm doing now only made use of Doclet APIs without touching JDK source code. I looked at before I started, it's completely a mess of legacy code. HTML markups are mixed with Java code. What current progressing solution is generate the JavaDoc as JSON files. And render the HTML in JavaScript. So I will prefer writing from scratch instead of modifying standard doclet. Adopot OpenJDK project is interesting, I will keep an eye on it. – chemhack Oct 24 '12 at 13:50

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