Javadoc: asterisk(*) intermixed with comments

[Derek Canaan]

Hi,
Problem:
-------
The DataFactory.html Javadoc generated includes asterisks intermixed in the comments as follows (note the asterisk between 'It' and 'guarantees; and at the end of the sentence:

suncertify.db
Class DataFactory
java.lang.Object
|
+--suncertify.db.DataFactory

--------------------------------------------------------------------------------
public class DataFactory
extends java.lang.Object
This singleton class provides access to Data objects. It * guarantees only one instance of Data per database file. *

Codes for this class is:

package suncertify.db;
import java.util.*;
import java.io.*;
[I][B]
/**
 * This singleton class provides access to <code>Data</code> objects. It
 * guarantees only one instance of <code>Data</code> per database file.
 *
 */[/B][/I]
public class DataFactory {
...
}

The javadoc command issued is:

D:\scjd>[B]javadoc -d .\docs -breakiterator -private suncertify.db[/B]
Loading source files for package suncertify.db...
Constructing Javadoc information...
Standard Doclet version 1.4.1
Generating .\docs\constant-values.html...
Building tree for all the packages and classes...
Building index for all the packages and classes...
Generating .\docs\overview-tree.html...
Generating .\docs\index-all.html...
Generating .\docs\deprecated-list.html...
Building index for all classes...
Generating .\docs\allclasses-frame.html...
Generating .\docs\allclasses-noframe.html...
Generating .\docs\index.html...
Generating .\docs\packages.html...
Generating .\docs\suncertify\db\package-frame.html...
Generating .\docs\suncertify\db\package-summary.html...
Generating .\docs\suncertify\db\package-tree.html...
Generating .\docs\suncertify\db\Data.html...
Generating .\docs\suncertify\db\DataFactory.html...
Generating .\docs\suncertify\db\InvalidFileException.html...
Generating .\docs\serialized-form.html...
Generating .\docs\package-list...
Generating .\docs\help-doc.html...
Generating .\docs\stylesheet.css...

Q. Why do the asterisks in the javadoc comments appears in the generated html file?
java version used is 1.4.1_02:

D:\scjd>java -version
java version "1.4.1_02"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_02-b06)
Java HotSpot(TM) Client VM (build 1.4.1_02-b06, mixed mode)

Any help is appreciated.
rgds,
derek
[ February 20, 2004: Message edited by: Derek Canaan ]

[Jay Bromley]

Hey Derek,
I'll take a whack at it. To me it looks like you don't have newlines at the end of your lines of code so javadoc sees your comments as one long string of characters on a single line. I believe javadoc removes asterisks when they are the first non-whitespace character on a line, so not having newlines could be the source of this problem.
This could be something related to your editor. Some editors (like jEdit, for example) do soft linebreaks or automatic wrapping, so you type until the end of the line and at some column less than 80 your editor automatically wraps, then you press tab to align the * and keep typing on the next line without inserting a newline. Soft linebreaks generally don't insert a newline when you save them so you get the one long line effect mentioned above.
Hope this helps,
Regards,
jb

[Derek Canaan]

Hi Jay,
You're absolutely right
I'm using UltraEdit. When i copy and paste the entire file onto NotePad and saved it as the same filename, run javadoc again, the problem disappears.
Now i have to find out which UltraEdit settings to change so that i don't have to do the same thing (copy, paste, and re-saved) for the rest of the files.
I would have never figured this asterisk-problem out. Thanks Jay .. you're great.
rgds,
derek
[ February 20, 2004: Message edited by: Derek Canaan ]

[Jay Bromley]

Derek,
Glad to have been of help. I'm not familiar with UltraEdit but you might look for something that mentions soft/hard line breaks. Sometimes this is tied up with auto-wrapping as well: soft linebreaks facilitate auto-wrapping since a newline doesn't have to be moved around when you change a line, breaking lines becomes purely a display trick. Good luck in finding the appropriate settings.
Regards,
jb