why is javadoc stuck in 1997?

92 views
Skip to first unread message

phil.s...@gmail.com

unread,
Oct 27, 2008, 12:25:28 PM10/27/08
to The Java Posse
Why is it that JavaDoc still doesn't have an embedded javascript
search and auto-complete. There are 1000s upon 1000s of classes now
and it's quite a pain to have to scroll through them.

Back in 1997 I understand it.... but there is no reason now. Everyone
uses a browser with javascript.

Has anyone addressed this?

Joshua Marinacci

unread,
Oct 27, 2008, 12:51:04 PM10/27/08
to java...@googlegroups.com
:) What do you think of this:

http://javafx.com/releases/preview1/docs/api/

Casper Bang

unread,
Oct 27, 2008, 12:57:32 PM10/27/08
to The Java Posse
The only other widespread alternative is DoxyGen no?
http://www.cypax.net/doxygen/html/annotated.html

The always impressive code generator Joshua Marinacci dabbled on a
neat prototype at some point:
http://weblogs.java.net/blog/joshy/archive/2007/03/posse_brain_dum.html

/Casper

On Oct 27, 5:25 pm, "phil.swen...@gmail.com" <phil.swen...@gmail.com>
wrote:

Mark Fortner

unread,
Oct 27, 2008, 1:06:29 PM10/27/08
to java...@googlegroups.com
Sweet.  Does that also work for the 99% of us who are currently using Java and not JavaFX? :-)

Mark
--
Mark Fortner

blog: http://feeds.feedburner.com/jroller/ideafactory

Joshua Marinacci

unread,
Oct 27, 2008, 1:10:16 PM10/27/08
to java...@googlegroups.com
It is part of the JavaFX SDK, but the javafxdoc tool does work on Java code as well.  
I'm up to my eyeballs in samples right now, but once we get the release out the door I'll have some blogs on how you can use it for Java code.
-j

Joshua Marinacci

unread,
Oct 27, 2008, 1:59:24 PM10/27/08
to java...@googlegroups.com

On Oct 27, 2008, at 9:57 AM, Casper Bang wrote:

>
> The only other widespread alternative is DoxyGen no?
> http://www.cypax.net/doxygen/html/annotated.html
>
> The always impressive code generator Joshua Marinacci dabbled on a
> neat prototype at some point:
> http://weblogs.java.net/blog/joshy/archive/2007/03/
> posse_brain_dum.html
>

The ideas I dabbled with here became the core of the JavaFX API docs
(which secretly work on Java code as well :)

- j

Christian Catchpole

unread,
Oct 27, 2008, 4:49:03 PM10/27/08
to The Java Posse
Check out my Doclet. It's called BonsaiDoc. I was frustrated that
generating JavaDoc created 30 meg of files and took ages to upload.
So the idea is that you get a quick overview in one file. And you can
expand class definitions to see the methods...

http://static.catchpole.net/bonsaidoc.html

Joshua Marinacci

unread,
Oct 27, 2008, 5:22:51 PM10/27/08
to java...@googlegroups.com
Very cool. Though that is a rather large file to load, but you only
have to load it once. :)

Christian Catchpole

unread,
Oct 27, 2008, 6:45:25 PM10/27/08
to The Java Posse
No one please look at the HTML. It doesn't use style sheets and is
padded with pre-formatted spaces. It is one big file but the
advantage of that is that it could be added to a build process without
much overhead. I could also add some options to create multiple files
by package or module or something.

Bill Robertson

unread,
Oct 27, 2008, 6:52:03 PM10/27/08
to The Java Posse
A really cheap fix is to use firefox, and to have the option that
begins searching as soon as you begin typing enabled.

On Oct 27, 12:25 pm, "phil.swen...@gmail.com" <phil.swen...@gmail.com>
wrote:

Kram

unread,
Oct 27, 2008, 7:58:44 PM10/27/08
to The Java Posse
I love the JavaFX API screen, however, I still think that dynamic
searching would be a fantastic feature, and widely used

On Oct 28, 3:51 am, Joshua Marinacci <jos...@gmail.com> wrote:
> :)  What do you think of this:
>
> http://javafx.com/releases/preview1/docs/api/
>

Joshua Marinacci

unread,
Oct 27, 2008, 9:55:29 PM10/27/08
to java...@googlegroups.com
Yep, and something we are working on for a future release.
-j

Alexey Zinger

unread,
Oct 27, 2008, 10:57:05 PM10/27/08
to java...@googlegroups.com
Keep in mind that standard javadoc pages do come with a single index page, which is of course searchable with most (all?) browsers.

Alexey
2001 Honda CBR600F4i (CCS)
1992 Kawasaki EX500
http://azinger.blogspot.com
http://bsheet.sourceforge.net
http://wcollage.sourceforge.net



--- On Mon, 10/27/08, Kram <mark.m...@gmail.com> wrote:

phil.s...@gmail.com

unread,
Oct 28, 2008, 10:58:10 AM10/28/08
to The Java Posse
The JavaFx thing is pretty cool, but I don't see search. Right idea
though.

There are certainly workarounds as others have suggested, but I just
don't get why sun doesn't just add this as default behavior....it's
odd. Kind of like how Microsoft hasn't updated the terrible command
console in 20 years and how Oracle's SQL Plus is still the same
terrible interface that it was 15 years ago. These are small/easy
things to fix with big impact.

It's a sign of a giant, bureaucracy-ridden company being driven by
clueless people IMO.

Weiqi Gao

unread,
Oct 28, 2008, 11:12:44 AM10/28/08
to java...@googlegroups.com

http://javac.info has a link that will add a "Java SE 6 API" search box
to Google Toolbar. Pretty useful. (There's one for "OpenJDK API" too.)

Too bad Google Toolbar is not available for Google Chrome.

--
Weiqi Gao
weiq...@gmail.com
http://www.weiqigao.com/blog/

Joshua Marinacci

unread,
Oct 28, 2008, 11:24:57 AM10/28/08
to java...@googlegroups.com
As I said in a previous email, search is not there yet but it's a
feature we are working on. I don't know if it will make it into the
1.0 release, however. Search is actually much trickier than you might
imagine because it has to work offline and in cases where someone has
downloaded the docs as a zip file and is viewing them off of the
filesystem rather than through a webserver.

phil.s...@gmail.com

unread,
Oct 28, 2008, 12:14:28 PM10/28/08
to The Java Posse
ya, it would have to be done all in local javascript. it's doable
tho.

On Oct 28, 9:24 am, Joshua Marinacci <jos...@gmail.com> wrote:
> As I said in a previous email, search is not there yet but it's a  
> feature we are working on. I don't know if it will make it into the  
> 1.0 release, however.  Search is actually much trickier than you might  
> imagine because it has to work offline and in cases where someone has  
> downloaded the docs as a zip file and is viewing them off of the  
> filesystem rather than through a webserver.
>

Joshua Marinacci

unread,
Oct 28, 2008, 2:11:46 PM10/28/08
to java...@googlegroups.com
Or an applet. :)

Michael Neale

unread,
Oct 29, 2008, 1:02:50 AM10/29/08
to The Java Posse
I (like Tor, I noted) pretty much use google exclusively for that.
Sometimes it confuses me, sometimes I am sans internet and then
realise I can't work without it ;)

On Oct 28, 3:25 am, "phil.swen...@gmail.com" <phil.swen...@gmail.com>
wrote:

wojciech.ha...@gmail.com

unread,
Oct 29, 2008, 3:21:07 AM10/29/08
to The Java Posse
How about jdocs.com? They have javadoc for several libraries. Search
is there, so is modern interface.

mbien

unread,
Oct 29, 2008, 4:37:37 AM10/29/08
to The Java Posse
On Oct 28, 7:11 pm, Joshua Marinacci <jos...@gmail.com> wrote:
> Or an applet. :)
> On Oct 28, 2008, at 9:14 AM, phil.swen...@gmail.com wrote:
>
I thought Sun does not use its own technologies ;)

sorry, just couldn't resist.

I prefere plain old and simple html pages over anything else which
looks interactive and consumer oriented without any usability
benefits. The old javadoc workflow is just perfect, start typing and
press return from time to time and you have your result within
seconds. I hope there will be a retro version of the javafx doc
without those javascript driven information hiding concepts.

But maybe this is more attractive for the JavaFX target audience since
they are probably more mouse and eyecandy driven anyway.

Viktor Klang

unread,
Oct 29, 2008, 5:41:36 AM10/29/08
to java...@googlegroups.com

Ouch! that's gotto hurt!

:D
 





--
Viktor Klang
Senior Systems Analyst

Marcelo Morales

unread,
Oct 29, 2008, 6:43:18 AM10/29/08
to java...@googlegroups.com
+1.
The simpler the better. I wouldn't mind javadoc in text files as long
as the IDE can parse it and I can read it.

Joshua Marinacci

unread,
Oct 29, 2008, 11:13:22 AM10/29/08
to java...@googlegroups.com

There will be a master index page that has the list of every class and
variable in the entire codebase. You'll be able to do this style of
find using that page. It was, ironically, asked for by one of our
designers. :)

>
> >

Bhavesh Patel

unread,
Oct 29, 2008, 6:45:45 PM10/29/08
to The Java Posse

Hi All,
We are working on a new Java documentation tool which will
have Java API documentation and much more. It is called DocWeb. More
information attached below. Please look at it. Besides, we have also
released a Javadoc plugin for NetBeans. You can download the plug-in
and access the Java API docs from within the NetBeans IDE. Go to Tools-
>Plugins-> Available Plugins and Install Java SE 6 API Doc English
Version.
Don't forget to look at the new design screen shots for
DocWeb.

Regards.


The DocWeb project aims to build a collaborative site for developers
to review, comment on, and translate API documentation for the Java
language classes. It is an open source project and is scheduled for
release in Q1 of 2009. The following features are planned in the
initial release:

In addition to viewing the Java API documentation, the DocWeb will
have

- Ability for developers to contribute comments and source code
samples related to specific Java classes, methods, constructors, and
fields.
- Integration with the online bug database pointing to bugs related to
specific Java classes, methods, constructors, and fields.
- Ability for developers to contribute API translations for dozens of
languages.
- Full translations for the Chinese and Japanese language.
- Ability to search Java API Docs by methods, field, package, or
class.
- Ability to view implementation source code for any class.

Resources:

- Open source project where docweb development is occurring:
http://docweb.dev.java.net
- Project management wiki: http://wikis.sun.com/display/DocWeb/Home
- New Design Screenshots: http://wikis.sun.com/display/DocWeb/New+Design+Screenshots

BoD

unread,
Oct 30, 2008, 5:26:33 AM10/30/08
to java...@googlegroups.com
Just a quick aside and I'm sure it's not relevant and not important, but
the French translations in the screenshots are completely bogus ;)

BoD

Viktor Klang

unread,
Oct 30, 2008, 5:28:59 AM10/30/08
to java...@googlegroups.com
Pardon their French.

Alex

unread,
Oct 30, 2008, 9:35:39 AM10/30/08
to The Java Posse
There actually is a moribund JSR 260 for overhauling Javadoc. As far
as I can tell, it has been targeted and slipped through a series of
Java releases but seems to be long dead.

On Oct 27, 11:25 am, "phil.swen...@gmail.com" <phil.swen...@gmail.com>

Bhavesh Patel

unread,
Oct 30, 2008, 3:16:03 PM10/30/08
to The Java Posse
Yes BoD. These screen shots are for new UI design and how the page
should eventually look. The translation or notes data you see might
not be accurate since it was just laid out to fill in the information
and eventually to build the design page.

Thanks.
Reply all
Reply to author
Forward
0 new messages