#472 Formats Javadoc Comments within a Method

[Paulo Ferreira]

First off, I'm actually using rc1 and not b5 (I don't
know if there is any difference).

The problem I'm having is 2 fold:
1. Jalopy is formatting javadoc comments within a method:
example:

public void method()
{
/**
* Line 1
* Line 2
*/
}

the comment in the method would be formatted to
/**
* Line 1 Line 2
*/

You might not consider this a problem, since
technically, these inner comments are not used for
javadoc, so there should be no problem in formatting or
not formatting.

But I'm using JASS
(http://csd.informatik.uni-oldenburg.de/~jass/doc/handbook.html)
which uses these comments to set the DoC limitations
for the functions.

2. Worse, JASS requires a Javadoc comment in a special
format
/** condition **/
(Note the 2 asterisk for the close of the comment)
this becomes
/**
* condition
*/
(Single asterisk for the close of the comment)
Which for JASS is an ERROR.

So basically jalopy is messing up my JASS Comments
everytime I format the source code.

I have a triemax jalopy license, and the triemax jalopy
ignored these inner comments (which I think is the
correct procedure).

[S]

Logged In: YES
user_id=723231

I agree that does make sense, for now though you could turn
off javadoc formatting which should preserve those comments
in the original format

[S]

Logged In: YES
user_id=723231

Would it be okay for the comment to be indented properly ?

Thanks

[Paulo Ferreira]

Logged In: YES
user_id=781961

The problem here is 2 fold:
1. JASS use the comment as /** .... **/ (So I can't lose the
closing **/ if formatted).
2. You can have a JASS Comment like
/** required oObject1 != null;
* oObject2 != null;
**/

Which would format to something like
/** required oObject1 != null; oObject2 !=
* null;
*/

Which might be okay JASS compile wise (I will check
tomorrow) but is not as readable.

[Paulo Ferreira]

Logged In: YES
user_id=781961

There is also a bigger problem with this in that, if I
include a JASS comment like:
/** require (nLevel >= 1) && (nLevel <= 4);
TypeMapUtilities.isValidType(nType);TypeMapUtilities.isValidGroup(nGroup);
**/

This will fail to format because of the '<' in (nLevel <= 4)
or '>' in (nLevel >= 1)

[S]

Logged In: YES
user_id=723231

I can work around the "bigger problem" by not performing the
parse of javadocs until they are actually ready to be
printed. The only disadvantage this has is that Jalopy will
no longer dismiss Javadocs completely (Which should never
occur anyways!).

Just let me know if you want jalopy to change the indent
level or not...

Thx

[Paulo Ferreira]

Logged In: YES
user_id=781961

Hi,

I Re-Opened this because I changed to 1.5rc3.

PROBLEM: **/
1. If the JASS comment is the 1st Comment after the {, the
**/ is converted to */
example:
public void method(Object oValue)
{
/** require oValue != null; **/ (Converted **/ to */)
}
2. In All Other Cases the **/ is maintained.

PROBLEM : Multi-Line JASS Comments.
FIXED (the Comments Maintain the Indentation and Format)
/**
* check ....;
* check ....;
**/
After Jalopy the format is the SAME.

PROBLEM: JASS Comment Indentation Level
I now understand the question you asked :)
The Correctly Formatted JASS Comments are all now at column 1.
NOTE: This doesn't apply to the 1st situation (example **/
above) since in that case the comment maintains it's
indentation level.

public void method(Object oValue)
{
/** require oValue != null; **/
....
/** check ....; **/
}

Formats to:
public void method(Object oValue)
{
/** require oValue != null; */
....
/** check ....; **/
}

COMMENTS:
I like the IDEA of formatting all the JASS Comments to
Column 1 (since it makes it standout from the rest of the
code). But on the other hand, I think the correct formatting
should be to maintain the indentation level.

POSSIBLE SOLUTION:
Jalopy control option, that would allow for JASS/method
JAVADOC comments to maintain the indentation level or be
formatted to column 1. (Best of both worlds solution).

PROBLEM: JASS Comments with < or >
Jalopy will fail when formatting code with these characters
(in both cases).

[Paulo Ferreira]

Logged In: YES
user_id=781961

I also forgot to mention that I noticed in the formatting of
class contstructor JavaDoc Comments there is a small proble
with the opening /** (I Don't know if it is related to this
problem or due to the changes to solve this problem)

example:

public class Test
{
protected Test(int nParam)
{
...
}
}

Formats to

/**
* DOCUMENT ME!
*
* @author Paulo Ferreira
*/
public class Test
{
/**
* DOCUMENT ME!
*
* @param nParam DOCUMENT ME!
*/
protected Test(int nParam)
{
...
}
}

Notice the indentation of the /** for the constructor (only
happens to constructors) all other methods are fine.