javadoc fixes

[Jens Elkner]

Hi,

Since java doc comments in the source are a little bit incomplete and sometimes
do not work (i.e. javadoc would not generate all the docs without errors, warnings
etc. out of the box) I would try to fix them.

Is anybody interested ?

If so, how can I make sure, that the fixes find their way back to the original sources?

Regards,
jens.

[David Gilbert]

Hi Jens,

I'm keen to have the Javadocs as up-to-date as possible, and any help will be appreciated. To get any changes back into the original source, you can either:

1) E-mail me the changes you make (I use JEdit with the JDiff plugin to review changes if you send me complete source files). Or you can send patches if you want.

2) Sign up on SourceForge, I'll add you as a developer on the project and you can commit your changes directly to CVS.

Regards,

DG.

[Jens Elkner]

Hi David,

IMHO, 2) sounds more handy for everybody and avoids additional work.

I hope, you are not annoyed by the style, I use:

- max. 80 chars/line
- tab indents, only
- tabwidth = 4

Regards,
jens.

My sourcefourge account is elkner .

[David Gilbert]

You've been added as a developer on the JFreeChart project at SourceForge.

Regards,

DG.

[Jens Elkner]

OK. So I´ll probably start on sunday working on it (next few days I need to do a little bit
in switzerland, which can´t be done remotely (((( )

Regards,
jens.

[Jens Elkner]

Finally I got the time to fix the real bugs. Others, which are a kind of "broken" in
jdk < 1.4.x are not fixed - it does not make much sense to me to suffix "e.g." with a
non-breaking space, so that the sentence continues but the readability vanishes.
1.4 handles these cases quite good using the -breakiterator option.

Further I applied some code conventions to the file I touched, to increase readability.
Basically linebreaks, indentation and curly brace alignments.

Next step would be, to add missing javadoc tags. Do you mind, if I continue as started?

[David Gilbert]

Hi Jens,

Regarding coding standards:

1) I've used spaces (4 per indent) rather than tabs because:

- I often cut and paste code into LaTeX files for documentation, and I haven't figured out how to get the layout right with tabs (like most things in LaTeX, it can probably be done, but I haven't spent any time finding out how);
- most code editors will allow you to configure the tab size to suit, but some display applications (such as the 'Browse CVS' option on SourceForge) don't, so in these cases spaces work better.

2) I've been using 100 characters for the right margin, rather than 80, on account of the fact that I use long variable names and 80 characters isn't much space.

1) is more of an issue for me than 2). Getting the Javadoc comments complete and accurate is more important to me than 1).

Regards,

DG.

[Jens Elkner]

Hi David,

wrt. 1) - many "old" people still think, that tabs are a problem today. Actually nobody
could give me a reason, not to use them, because only very ancient and poorly written
software can not handle them. But for me it is important to have tabs, since I'm not
a finger artist, which is able to press 4 keys with one hand to be able to navigate
through code. Also tabs are better, since ppl can always choose, how far to indent
the code by setting the tabwidth, so it's even more flexible

BTW: LaTeX: What editor? Perhaps I have a hint, If it is a UNIX based one or emacs.

wrt. 2) ok, but I have not always an IDE at my fingertips. I often use terminals, which
have only 80 chars/line. It does not matter, whether I use auto-wrap or not, in one case
I loose things since I can´t see them, in the other case readability breaks and I often
loose important things as well (OK, not at my company, since there I can say:
"Do it again, Sam!" ). So 80 is my limit to do a good job.

So as you said, I´ll continue with tab4,80 - but this makes only sense, if other coders
use tabs + 80 as well, otherwise we would waste our time with re-indenting again
and again...

Regards,
jens.

[David Gilbert]

Jens Elkner wrote:
- but this makes
> only sense, if other coders
> use tabs + 80 as well, otherwise we would waste our time with
> re-indenting again
> and again...

I choose not to impose coding standards on contributors. The reason is that there is a burden on developers either way:

- WITH coding standards, developers are forced to adopt a standard that don't like (for whatever reason);

- WITHOUT coding standards, developers are forced to read code that isn't formatted the way they like;

The latter means I don't have to spend too much time defending a particular set of rules. Everyone thinks coding standards are a great idea, as long as they get to use their own...

Regards,

DG.

[Jens Elkner]

OK.

The biggest part chart.* is commited and should be clean - i.e. no missing tags and some fixed.

chart.HorizontalIntervalBarRenderer.hasItemGaps()
chart.HorizontalMarkerAxisBand{}
chart.IntervalMarker{}
chart.JThermometer{}
chart.MeterPlot{}

have not much info, so some comments should be added to them, too.

BTW:
I saw all the flags in the constructors of *Axis stuff. Wouldn´t it be much better and
less error prone, if one uses just an int and static "binary" values for all the
flags? Thus passing all infos around is easier and the addtion of a new flag (e.g.
it looks like crosshairInfo and crosshairVisble were such "extensions") would not
require to touch any class, since they simply ignore the values, they do not know
something about.

Regards,
jens.