API docs / gjdoc

[david.gilbert]

I've created a set of API docs for JFreeChart using 'gjdoc' which is part of the GNU Classpath project:

http://www.jfree.org/jfreechart/api/index.html

These API docs look great using Mozilla Firefox on Linux, but I've already learned that they look bad using Microsoft's Internet Explorer on Windows. I'd like to provide some feedback to the gjdoc developers, so I'd be really grateful if you could browse the API and post your feedback (be sure to state your browser version and operating system).

[gumshoe]

Looks fine using Firefox 1.0.2 on XP.

[j0medina]

Looks good on both Firefox 1.02 and IE 5.50.4807.2300CO on Windows 2000 SP 3.

[Alex Manoylenko]

All is kewl using IE 6.0.2900.2180 XP SP2.

[timw]

Start of words are cut off in tables when using IE 6.0.2900.2180 XP SP2.

For example, looking at class AbstractXYItemLabelGenerator. Under Constructor Summary, only YItemLabelGenerator is visible, rest has been chopped off.

Same applies for Method Summaries. eg. createItemArray only shows mArray.

[Alex Manoylenko]

Hi, Tim.

Sorry. You are right, methods are cut at the beginning

Best regars, Alex

[mhilpert]

Same with Windows 2000 SP4. Worst example is org.jfree.data.Range : most method names are not visible.

This layout is also very hard to read. All the rectangles for parameters distract you from the content - you just see a lot of lines and get a headache after a while.

I wonder why developers write such different unreadable layouts as the javadoc layout is very intuitive, the fonts are clear and readable (not as small as with this jgdoc) and the generated HTML looks equal in all browsers.

[Taqua]

Well, looking at the W3C validator, this page seems to be garbage.

[url=http://validator.w3.org/check?uri=http% ... +Europe%29]Validate it[/ul]

That firefox/mozilla renders that code correctly must be purely accidental - as that code is definitly not valid HTML.

Have mo' fun,
said Thomas

[david.gilbert]

That firefox/mozilla renders that code correctly must be purely accidental - as that code is definitly not valid HTML.

I noticed that problem too. Javadoc also generates invalid HTML. Since I have the gjdoc source code, I am going to experiment with it and see if it can be made to generate valid XHTML 1.0.

[david.gilbert]

Some great news...Julian Scheid, the developer of 'gjdoc', has committed changes to gjdoc CVS so that it generates valid XHTML - excellent work!! Now we can just wait for the 'javadoc' developers to do the same:

http://bugs.sun.com/bugdatabase/view_bu ... id=4663254

Unfortunately, Internet Explorer (IE) still does a poor job of rendering the 'gjdoc' output (it looks great in the other browsers I've tried). Julian has said that he will experiment with the style sheets to see if there are workarounds to the problems in IE.

Please feel free to provide any further (non IE-related) feedback on the 'gjdoc' output.

[BigWillyStyle42]

Honestly, it just looks like a crappy version of Sun's Javadoc. Why not just stick with Sun's documentation generator? It's what most Java programmers expect, it's easy to use, and it looks fine.

[david.gilbert]

Honestly, it just looks like a crappy version of Sun's Javadoc.

What things in particular make it look "crappy"? Honestly, on my system (fairly standard Gentoo Linux on AMD64, with Firefox as the browser) the gjdoc output looks a little better (cleaner) than the javadoc output. But I am interested to know how it looks on other systems, because the feedback will help to make gjdoc better.

Why not just stick with Sun's documentation generator? It's what most Java programmers expect, it's easy to use, and it looks fine.

I prefer free software, for a variety of reasons. Eventually I'd like to eliminate my dependency on Sun's JDK completely - it is the *last* item of closed-source software on my systems. So I help out where I can to promote free alternatives.

The javadoc output hasn't gone yet, it is still at:

http://www.jfree.org/jfreechart/javadoc/index.html

But I do plan to switch to gjdoc exclusively as soon as the issues with Internet Explorer are fixed.

[BigWillyStyle42]

Honestly, it just looks like a crappy version of Sun's Javadoc.

What things in particular make it look "crappy"? Honestly, on my system (fairly standard Gentoo Linux on AMD64, with Firefox as the browser) the gjdoc output looks a little better (cleaner) than the javadoc output. But I am interested to know how it looks on other systems, because the feedback will help to make gjdoc better.

Everything is extremely boxy, whereas Sun's output even though it has almost the same layout looks much less boxy. I'd attribute that to:

1. Sun filling in the headers with a different color (light blue).
2. Sun's borders being smaller so they look more like lines instead of a rise or depression.
3. Paramaters and return value for functions are surrounded in boxes, which is wholly unnecessary, and the text inside is centered which makes it more difficult to read.
4. In the package listing the packages are right aligned, something that is typically only used for numbers, not text which is meant to be read from left to right.
5. At the top and bottom the links for overview/package/class/etc are surrounded in boxes which are again unnecessary and add to the boxy feel of the page.
6. It is an utter rip off of Sun's layout.

Why not just stick with Sun's documentation generator? It's what most Java programmers expect, it's easy to use, and it looks fine.

I prefer free software, for a variety of reasons. Eventually I'd like to eliminate my dependency on Sun's JDK completely - it is the *last* item of closed-source software on my systems. So I help out where I can to promote free alternatives.

This is a very bad idea in my opinion. There is only one JVM that is what I'd call "standard" and that is the one produced by Sun since they define Java. To develop your application on a non-standard JVM might reduce your code's interoperability with other JVM's which attempt to implement the Java standard.

And you said you like free software, last I checked nobody has to pay to download the J2SDK or J2RE. Additionally Java's source code is available for download from Sun's website, so it's not really closed source.

[david.gilbert]

Everything is extremely boxy...

From your description, it sounds like you are using Internet Explorer. If you are interested to see how the output should look, try it with Firefox. The IE issues will be worked on.

This is a very bad idea in my opinion. There is only one JVM that is what I'd call "standard" and that is the one produced by Sun since they define Java. To develop your application on a non-standard JVM might reduce your code's interoperability with other JVM's which attempt to implement the Java standard.

Sure, interoperability is important. I also contribute a lot to the Mauve project, which is a free test suite for checking compliance with the Java specifications. Mauve is approaching 30,000 tests now, and continues to grow with input from many developers. It is an important tool that can be used by *all* implementations of the standard Java class libraries, including Sun's (Mauve picks up a number of bugs in various versions of the JDK).

I've also read that Dalibor Topic from the Kaffe project is negotiating with Sun for access to Sun's TCK to test Kaffe's (and therefore GNU Classpath's) compliance with the Java specifications. Compatibility is something that the free runtime projects do take seriously.

And you said you like free software, last I checked nobody has to pay to download the J2SDK or J2RE. Additionally Java's source code is available for download from Sun's website, so it's not really closed source.

I'm referring to "free software" as defined by the Free Software Foundation:

http://www.gnu.org/philosophy/free-sw.html

Sun's Java is not free software. And while it can be said that Java is not "closed source", it certainly isn't "open source" in the generally accepted sense:

http://www.opensource.org/docs/definition.php

[Taqua]

Well, I also think that the gjdoc tool produces ugly looking docs. Reducing some of the borders will make it look better.

I would support all of your points, except the last one. Yes, it 'inspired' by Sun's tool - but I'm quite sure that as soon as the tool is more developed, they will start to head into an own direction. Usually most projects start by cloning ideas from successfull solutions.

Code: Select all

This is a very bad idea in my opinion. There is only one JVM that is what I'd call "standard" and that is the one produced by Sun since they define Java. To develop your application on a non-standard JVM might reduce your code's interoperability with other JVM's which attempt to implement the Java standard.

Sun itself declares, that it wants the community to decide what features should go into the java releases. Thats what the Java Community Process is for. But Sun is the harsh king, that chops down heads and ideas, which seem not to fit into the corporate ideal of Sun. I agree - making sure that Sun's Java works with our tools is important - but supporting the free alternatives is as important as following the standard.

Free software is all about choice - to have several alternatives to choose from - or if they do not exist: to create one. Honestly, I don't see a clear strategy behind Sun's opensource projects. They have OpenOffice (LGPL), they have NetBeans (MPL) - both are truely opensource projects. Now the OpenSolaris, which is called open (marketing?), but is not fully opensource yet (and it might take years to get there, if they manage to attract developers). So they *are* able to create opensource projects and are able to use them in your commercial plans (like the staroffice-openoffice thing, or netbeans/forte). But for some reason they can't get a real answer to whether they would release Java as opensource (OSI approved!) or not. Until then, Java is at the same level of freedom as .NET or Windows.

Interoperatibility and opensource is no contradiction in terms. X11, Posix et. al. are standards well known in the closed source world, and adopted and brought to new life in the open source world. OpenSource creates standards - look at the OASIS opendoc specifications, which eveolved from OpenOffice.org and will be widely used in OpenOffice, KOffice and other free software projects (while MS happily anounces that its next office version will finally ZIP their XML file format (a proprietary one of course) - they should have looked as OpenOffice: even the 1.0 version used ZIP archives ).

Code: Select all

And you said you like free software, last I checked nobody has to pay to download the J2SDK or J2RE. Additionally Java's source code is available for download from Sun's website, so it's not really closed source.

There is a difference between free software and libre software. We talk about libre software here. And as soon as you try to, for instance, port the JVM to a new system (ARM for instance), you will get a nice talk with Sun's lawyers. You are not *free* to use the code for your purposes to the same extend as you are free to use and modify JFreeChart, Eclipse or Mono.