Bug 222900

Summary:

[Javadoc] Missing description is warned if valid description is on a new line

Product:

[Eclipse Project] JDT

Reporter:

Martin Oberhuber <mober.at+eclipse>

Component:

Core

Assignee:

Frederic Fusier <frederic_fusier>

Status:

VERIFIED FIXED

QA Contact:

Severity:

normal

Priority:

CC:

daniel_megert, dave.wichers, david_audel, hello, hk, jerome_lanneluc, kai.mechel, markus.kell.r, mauromol, philippe_mulet, wolfgang.knauf

Version:

3.4

Target Milestone:

3.5 M2

Hardware:

All

OS:

All

Whiteboard:

Bug Depends on:

73352

Bug Blocks:

Attachments:

Description	Flags
Proposed patch	none

Description Martin Oberhuber

2008-03-16 14:46:53 EDT

Window > Preferences > Java > Code Style > Formatter
  Profile "Eclipse [built-in]"
  --> Commnets : New Line after @param tags is switched ON by default

This setting conflicts with the following new compiler warning feature if enabled, which was added in 3.4M3 as per bug 73352:

Window > Preferences > Java > Compiler > Javadoc
  Malformed Javadoc Comments: Warning
  Missing tag descriptions: Validate all tags

This is particularly problematic when "Format Code" is enabled as "On Save" operation, since the user has no chance getting it right in this case.

I think that either the default "Eclipse" profile should be changed to not add a new line after @param tags, or the "Missing tag descriptions" compiler warning should not issue a warning if the tag is there but on a new line.

Actually, the second solution seems better since the javadoc tool also accepts @param arguments on a new line, so the warning is incorrect in this case.

Comment 1 Martin Oberhuber

2008-03-16 15:07:36 EDT

Changed summary, previous value was:
[formatter] Default "Eclipse" profile conflicts with "Javadoc tag missing argument" compiler warning for @param

The point is really that the "Javadoc: Description expected after this reference" warning is invalid if the reference is there but on a new line.

Comment 2 Philipe Mulet

2008-03-16 23:49:31 EDT

Yes, I agree the warning should tolerate the new line.

Comment 3 Eric Jodet

2008-06-26 10:18:35 EDT

*** Bug 238590 has been marked as a duplicate of this bug. ***

Comment 4 Mark Hobson

2008-07-29 11:59:27 EDT

This bug causes valid source code to be littered with warnings when descriptions are on new lines - can this be targeted for 3.4.1 please?

Comment 5 Frederic Fusier

2008-08-21 05:30:42 EDT

*** Bug 244785 has been marked as a duplicate of this bug. ***

Comment 6 Dani Megert

2008-08-26 09:37:30 EDT

Can this be fixed for 3.5? If we enable to check all tags and not just @return we get many false warnings.

Comment 7 Mauro Molinari

2008-08-26 12:21:22 EDT

(In reply to comment #6)
> Can this be fixed for 3.5? If we enable to check all tags and not just @return
> we get many false warnings.

I hope it is considered for 3.4.x, too... It's quite annoying...

Mauro.

Comment 8 Jerome Lanneluc

2008-08-27 12:34:48 EDT

This is too late for 3.4.1. But we should have a look for 3.4.2 if it is a regression comparing to 3.3.2.

Comment 9 Kai Mechel

2008-08-30 04:47:23 EDT

It would be great, if the fix could be scheduled for 3.4.2
As long as it is not fixed, I format the code without new lines after @param tags. But this doesn't look very pretty.

Comment 10 Frederic Fusier

2008-09-02 03:54:12 EDT

Created attachment 111453 [details]
Proposed patch

Instead of verifying the end of line to report the missing description warning, the Javadoc parser waits either the next tag, the closing brace of the in-line tag or the end of the comment to warn if the description hasn't been set for the previous tag...

Comment 11 Frederic Fusier

2008-09-02 03:58:49 EDT

I do not intend to backport this fix in 3.4 maintenance stream because
1) it's too big and risky
2) this cannot be considered as a regression as this problem only happens when user selects the new preference: "Missing tag description - Validate all standard tags".

The workaround for 3.4.x versions will be to keep using the default preference for this warning: "Missing tag description - Validate @return tag".

Comment 12 Frederic Fusier

2008-09-02 04:09:29 EDT

Released for 3.5M2

Comment 13 David Audel

2008-09-15 07:31:32 EDT

Verified for 3.5M2 using I20080914-2000

Comment 14 Frederic Fusier

2008-10-17 03:57:38 EDT

*** Bug 251160 has been marked as a duplicate of this bug. ***

Comment 15 Frederic Fusier

2008-10-25 11:49:23 EDT

*** Bug 252088 has been marked as a duplicate of this bug. ***

Comment 16 Frederic Fusier

2008-10-25 11:50:35 EDT

*** Bug 252088 has been marked as a duplicate of this bug. ***

Comment 17 Frederic Fusier

2009-02-11 05:01:19 EST

*** Bug 264415 has been marked as a duplicate of this bug. ***