2

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?

Improve this question
4
  • 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
    Commented Oct 24, 2012 at 13:00
  • Actually, the standard doclet uses frames and not iframes which is a lot worse.
    – Ingo Kegel
    Commented Oct 24, 2012 at 13:02
  • I would expect it not forcing me to re-learn and re-memorize things I learned and memorized with "old bad" javadoc
    – gnat
    Commented Oct 24, 2012 at 13:16
  • 2
    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.
    – user53019
    Commented Oct 24, 2012 at 13:26

1 Answer 1

Reset to default
5

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.

Improve this answer
1
  • 1
    What I'm doing now only made use of Doclet APIs without touching JDK source code. I looked at com.sun.tools.doclets.formats.html 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
    Commented Oct 24, 2012 at 13:50

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.