Rick and I are excited and nervous. We're excited because the time has come to make a preliminary introduction of our new JDocs.com community documentation project. We're nervous because it's impossible to know in advance whether JDocs.com is something you will find truly useful. JDocs.com is a move in a new direction for Javalobby. We decided to push it live in preliminary form specifically so that our development priorities can be shaped by your needs and desires. The future of this service will be driven directly by the feedback we receive from you. We want JDocs.com to deliver maximum user delight, providing you with a tool you'll be truly pleased to have, regardless of whether you have previously envisioned a need for it.

JDocs.com is a dynamic, database-driven repository of javadoc information for a large and growing number of popular Java packages. With javadocs for 50 APIs already loaded, we think JDocs.com could soon become the largest repository of its type. We expect that the number of APIs supported by JDocs.com will climb significantly, perhaps eventually reaching several hundred. It's neat to have a one stop shop for javadocs. In fact, many of our early users have told us that what they like best about JDocs.com is having all this API documentation in one place.

JDocs.com goes beyond merely consolidating this API documentation, however. Following the successful example of PHP.net and MySQL.com, virtually every class and method in the JDocs.com repository can be enhanced by "user contributed notes." You can ask questions or give answers, share tips and insights, post code examples, and provide links to related articles and other resources. In essence, JDocs.com leverages the javadocs as an organizing structure for what could become a vast knowledge resource for real Java developers. The javadocs are a natural place for community-based knowledge to be stored, placing relevant information about the APIs right where you need it… in the documentation!

The API search capabilities of JDocs.com will also provide valuable perspectives on the treasure house of information in the repository. We're eager for your input as we explore the complex question of what constitutes a really good API search? The early contributions of some very bright developers have already helped us deploy a search that is both potent and fast. We anticipate that the API search will become one of the most important functions of JDocs.com, and our goal is to make it quick and easy for you to find that needle in a haystack you have been looking for.

It's up to you now. The fate of this new service is ultimately in your hands. JDocs.com will need active contributors and moderators to make our community vision a success. Rick and I both want to believe that the best side of the Java community will shine brightly as developers share knowledge and insights to help one another be more productive and successful. Our progress so far leaves us with no doubt that we can make JDocs.com work technically, but only you can make it work as a community. We hope that you will.

I have been using JDocs.com for a short time, and it is really interesting. I really hope it grows!

Two questions:

1. Is it possible to search on any specific API and not on all APIs.

2. Help link gave me a message:

HTTP Status 500 -

type Exception report

message

description The server encountered an internal error () that prevented it from fulfilling this request.

exception

java.lang.StringIndexOutOfBoundsException: String index out of range: -1
java.lang.String.substring(String.java:1444)
org.javalobby.jdocs.filters.SunURLHandler.getPackageString(SunURLHandler.java:237)
org.javalobby.jdocs.filters.SunURLHandler.doFilter(SunURLHandler.java:140)
edu.yale.its.tp.cas.client.filter.CASFilter.doFilter(CASFilter.java:194)

note The full stack trace of the root cause is available in the Apache Tomcat/5.0.27 logs.
Apache Tomcat/5.0.27

Oleg

Hi Oleg,
   We're aware of both of these and are actively working on correcting the search to allow for per-api search. The help link will also be corrected - most likely tomorrow.

How JDocs plan to support new API versions of the libraries? JDocs loses all old comments when a new version is posted? Or the comments stay but refer to the version that was active at the time of the writing?

JDocs will carry forward and back the comments, noting what version those were made on I believe. Nothing will be lost unless a method doesn't exist.

the search really needs to be improved. For example, search for 'Map'.. the top results are from the jakarta collections and java.util.Map isn't even on the first page. I couldn't paginate through search results so I have no idea how buried it actually is.. Some sort of pagerank weighting system is obviously in order.. Next, I tried narrowing my search to "util.Map" with 0 results returned.. so some stemming support and/or more advanced token parsing would also help.
Great idea though.. mysql and PHP provide stellar examples of community documentation.

We're actively working on the search and already we've got several new features integrated into it, along with allowing you to drill into it more. We'll try to get a page up that tells you how to do advanced searches.

Uh, the most common use case - simply getting to the Javadoc for a given class - is a bit too far away. Searching for, say, "String" will give you a page with search results for "String", from where you go to the actual API page. I know, every API may define a new String class, one of which you may be looking for, but usually aren't you simply looking for java.lang.String (OK, bad example, but think javax.swing.JLabel - much less chances of collision) and want to get there as quick as you can?

javadocs.org solved this by doing a Google "I'm Feeling Lucky!" search for the search item, but then they lost the navigation panes. Even with plain Google and the Lucky button, I can usually get there faster.

Can the more extensive search be an option, and the default a straight-on search?

Another thing - and this might be a fancy but useful feature : what exactly governs the ranking of a search result? Overall Google search ranks or the search rank on JDocs.com itself? I mean, if many more users of JDocs.com search for java.lang.String than for.example.hibernate.String, does the former show up earlier in the search results?

Ideally, I would like to see rankings applied to the navigation panes as well. What I mean is, as of now I have the Sun JDK javadoc page bookmarked, and that has those library and package navigation panes down the left. I end up looking in java.lang, java.util, java.awt or javax.swing most of the time, but because the panes are sorted alphabetically there's a lot of navigation to do. If the entries in these panes were sorted, or at least highlighted, by frequency of being summoned, it would be a big help.

Looks like you use Google Search, and Google does not search for incomplete words. A big drawback in API searching.

Well done on a good start.
The search definately builds on previous javadoc stores that there have been.

Couple of ideas.

- Versioning; should just be one link per project i.e. Web Work 1 and Web Work 2 should just be one link surely ?

- Categories; I guess as the number of api's grows as well as the 'all' list there will need to be a few Categories / Sections (suggest sun api's given their own section?)

- Non functional description of each api. i.e. not all documention is javadoc, I guess there will be a page some place giving an overview of the api, and the envisaged way of using it.

- Existing Examples; many of the API's have quite good existing webpages with example code on them - could possibly be fully integrated, else the url referenced.

- Quick Links to the API homepage, and the downloads page. Could be just small W and D icons.

- Registration link nr the logon (sure i had a lobby pass at some point!!)

Ok thanks for this, was only discussing it with a mate last week after thinking why has java not got anything as good as php.net after such a long existance?

Ian

As per subject line. I have a feeling this or something like it may cause a small revolution in java coding.

This actually seems like a great idea.

May need to figure out how to filter out "noisy" user comments in the Javadocs, though.

If this works out, its not a real stretch to imagine IDE plugins, etc. to access this content, sort of a Developer's Almanac on steroids.

Can you imagine a "sample code" browser for certain APIs?

User: "How do I read files in Java?" - search for "file reading"
System: Return a list of APIs with links to sample code for file reading

Better get some more servers ;)

We hope its going to be a big idea as well. We'll be heavily moderating the comments that don't fit in and we already have a team in place to make sure that happens. We're also looking at some software that allows us to execute sample code from the website.

We'll get those new when you guys keep coming back to the site and delivering those views.

We've got live code examples embedded in Javadocs, and support JDK 1.4, 1.5, servlets, JSPs, Perl, Python, Groovy and more. Yes, we have IDE plugins.

http://zamples.com

All I can say is that this a brilliant idea. Once every blue moon someone comes up with something that jumps out as necessary, intelligent, and startling obvious. This definitely belongs in that camp. I can only imagine the impact this will have not only on developer productivity, but on improving the quaility of APIs.

And I'm not just saying this because Mathew reviewed my book :-).

Kito D. Mann
Author, JSF in Action
http://www.JSFCentral.com - JSF FAQ, news, and info

You've just allowed me the chance to delete a number of bookmarks. The Firefox/Mozilla search plugin is fantastic. Great job guys!

I can see this growing into a CJAN. Combine the usefulness of this plus what maven repositories should be, and things could get really useful.

I don't know if this would be usefull to anyone but me but I would like to be able to get view a list of new comments added to a api. I've looked arround in the api's just to see if someone added a comment somewhere but dident find anything. Like reading usefull tips in blogs i could go there to read them too.. if i could find them. In time im sure it wont be difficult to find any but it will still be usefull to get a view of the lastest.

I don't know if this would be usefull to anyone but me but I would like to be able to get view a list of new comments added to a api. I've looked arround in the api's just to see if someone added a comment somewhere but dident find anything. Like reading usefull tips in blogs i could go there to read them too.. if i could find them. In time im sure it wont be difficult to find any but it will still be usefull to get a view of the lastest.

We're definitely planning on this, we've got the tags for it, just have to rearrange the frontpage a bit to display it.

It could be very usefull to be able to add sample code to the methods and classes. Something like http://www.javaalmanac.com (which I use very often).

Ernst

Hi,

I created a Taglet to display sample (under LGPL). You could see a sample result (and the source code usage) at : http://www.dwayne.freesurf.fr/my-lib/api/my/config/Configuration.html

There is some bug (also in javadoc), but I expect to publish it early. (code display use java2html (http://www.java2html.de/)).

We're actively looking for a way to include samples and have had contacts with the guys over at Zamples. Please email me at matt at javalobby dot org so we can take a look at what you have.

Congratulations. This really is a brilliant idea.

UML diagrams might also be helpful for certain packages--have you considered that?

Also, do you plan to run parallel versions of the docs for popular projects (say latest production release and latest beta)?

Congratulations. This really is a brilliant idea. UML diagrams might also be helpful for certain packages--have you considered that?Also, do you plan to run parallel versions of the docs for popular projects (say latest production release and latest beta)?

Once we have the versioning straightened out we can run as many concurrent versions as we want. We also will be probably displaying UML from yDocs sometime in the near future.

ok, no good pointing out why this is absolutely brilliant.
So lets get to my suggestions:
-integration plugins for IDEs (IDEA, eclipse, ...), or somehow provide a hook to their javadoc URL mechanism
-version managagement is extremely important in this rushing world of open source. You cannot always justify to migrate to the newest version 2.3.4.1, especially when the version 2.3.3.6 works perfectly well for you

version managagement is extremely important in this rushing world of open source. You cannot always justify to migrate to the newest version 2.3.4.1, especially when the version 2.3.3.6 works perfectly well for you

Yep it would be great if you could set personal prefferences for versions, and have it search the latest versions by default

There are some conspicuous omissions, for example why is javax.xml.* missing from J2SE? This makes me nervous about relying on JDocs as my principle reference - what else might be missing?

There are some conspicuous omissions, for example why is javax.xml.* missing from J2SE? This makes me nervous about relying on JDocs as my principle reference - what else might be missing?

Yea, someone else noticed this. I believe that most things are there due to the fact that I use the the package-list from the actual project websites to generate our docs. I believe J2SE was done in the project we based JDocs on and it may be missing those packages. We'll add those in as soon as possible.

Much needed... great work to start with. Couple of suggestions (some of which have already been mentioned in earlier posts):

1. Register/Login. So I can choose which version of a particular API I want to see/search. Also, adding some other useful preferences might help, like api-search-order, tree-view/flat-view, number-of-results-per-page etc...

2. API categories. Sun's documentation should definitely be separate. I would like to see some useful checkboxes by the side of my search box, like I/O, Remoting, Web-Frameworks, only-examples-search, only-docs-search etc...

3. UML diagrams. I know you are already working on this one :-)

4. RegEx Search. So I can reach there faster by seeing only results matching a specific pattern.

5. Latest activity pane. Which shows the latest activities happening on JDocs in reverse chronological order. That will bring me to JDocs.com not only when I am looking for API docs or usage comments, but also for general techie reading ;-)

6. Community supplied modules. Like CPAN, users should be able to contribute useful wrappers around common classes, or extend API classes for more specific purposes. Take me to the documentation first, from where I can download the module itself.

Other than that, your Search seems to be very slow sometimes. I will definitely stay tuned guys... Hope you turn it around soon...

chEErs,
aXe!

Also check <

Damned, got cut! :-(

Also check out http://www.allimant.org/javadoc/ for some Java documentations in WinHelp and HTMLHelp format. I find those invaluable in day-to-day work.

I've read that news a few hours ago, like the idea, started hacking. The result is nothing real funky, but a good start I think. Some even might it useful :)

Check the screenshots, feel free to install. Provided as-is, without warranty of any kind, etc :)

http://ond.vein.hu/~dyn/updatesite/

cheers,
dyn

I've read that news a few hours ago, like the idea, started hacking. The result is nothing real funky, but a good start I think. Some even might it useful :)Check the screenshots, feel free to install. Provided as-is, without warranty of any kind, etc :)http://ond.vein.hu/~dyn/updatesite/cheers,dyn

Holy Crap! You rock man! Please email me at matt at javalobby dot org so we can discuss how to give this more exposure at JDocs and get some other people thinking about how to improve it. I love the right click and "Search on JDocs" - very cool!

Did you submit your plugin to the Eclipse plugin sites?

http://eclipse-plugins.2y.net/eclipse/index.jsp

What ActiveX controls do you use? I have them turned off in my IE. But I hate clicking OK on "You current security settings prohibit running ActiveX controls" dialog.

What ActiveX controls do you use? I have them turned off in my IE. But I hate clicking OK on "You current security settings prohibit running ActiveX controls" dialog.

If we are, I certainly don't know it. We don't use anything ActiveX. The only Flash you'll see would be in some of the ads. Other than that, its all straight HTML.

What ActiveX controls do you use? I have them turned off in my IE. But I hate clicking OK on "You current security settings prohibit running ActiveX controls" dialog.

If we are, I certainly don't know it. We don't use anything ActiveX. The only Flash you'll see would be in some of the ads. Other than that, its all straight HTML.

I see, than it is probably Flash ActiveX. Actually, the primary reason to turn ActiveX off was the desire to get rid of Flash.

Rick and I are excited and nervous. We're excited because the time has come to make a preliminary introduction of our new JDocs.com community documentation project.

Cool. Thanks for build this.

It kind of reminds me of Macromedia's Livedocs web site

http://livedocs.macromedia.com/flashremoting/index.html

http://livedocs.macromedia.com/flex/1/flex_docs/wwhelp/wwhimpl/js/html/wwhelp.htm

Actually there is already existing WEB Site http://www.kickjava.com/
that featuring JavaDocs and examples/comments with usage...

I would work with them to coordinate your efforts.