Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 168925

Summary:	[javadoc] Change default for 'Malformed Javadoc' to warning
Product:	[Eclipse Project] JDT	Reporter:	Martin Aeschlimann <martinae>
Component:	Core	Assignee:	JDT-Core-Inbox <jdt-core-inbox>
Status:	CLOSED WONTFIX	QA Contact:
Severity:	normal
Priority:	P5	CC:	frederic_fusier, philippe_mulet
Version:	3.3	Keywords:	helpwanted
Target Milestone:	---
Hardware:	PC
OS:	Windows XP
Whiteboard:	stalebug

Description Martin Aeschlimann

2006-12-22 04:05:36 EST

3.3 M3

I think the compiler Javadoc support is really good, but novice users don't know of it as the default is to not report Javadoc warnings.
There are also misunderstandings as in bug 168161.

To promote this feature, I suggest to set the defaults pf 'Malformed Javadoc' to 'Warning', as visible as 'Private', 'Report errors in tags' to 'Enabled'. All other options to 'Disabled' or 'Ignore'

Comment 1 Frederic Fusier

2006-12-22 04:28:25 EST

I do not really agree as this support has a cost while compiling (around +5%) and we really want user to set it intentionally... Otherwise, when changing this default user may complain that compiler is now slower than previous version!

A possible suggestion would be to show javadoc comment differently when it's parsed than when it's not (color/style) or show a specific hover when flying over it?

Comment 2 Martin Aeschlimann

2006-12-22 04:37:53 EST

By default 'Process Javadoc' is turned on, and imports are not marked as 'unused' when the are only referenced in Javadoc.
So there already seems to be some processing of Javadoc. Is the reporting really adding 5% to that?

Comment 3 Frederic Fusier

2006-12-22 06:17:34 EST

(In reply to comment #2)
> By default 'Process Javadoc' is turned on, and imports are not marked as
> 'unused' when the are only referenced in Javadoc.
> So there already seems to be some processing of Javadoc. Is the reporting
> really adding 5% to that?
> 
You're right, we're processing javadoc comments by default, so forget my previous comment... My mind in vacations does not work so well... ;-)

However, users then might have tons of warnings (which would also slow compilation but far less than Process Javadoc option) and could complain about that; but I agree this argument is not so important...

Philippe, would you be happy with these new defaults?

Comment 4 Martin Aeschlimann

2006-12-22 06:31:22 EST

We have to see how many new warnings will apear. Note that I only suggest to turn on malformed comments, where you reference unknown classes or wrong param tags.
If it's too much, we could add compaitibility code for existing workspaces.
After all, I think if users create Javadoc comments (instead of normal comments) the should better have them correct.

Comment 5 Frederic Fusier

2008-09-04 12:13:57 EDT

Ownership has changed for the javadoc comments bugs, but I surely will not have enough time to fix your bug during the 3.5 development process, hence set its priority to P5.
Please provide a patch if you definitely need the bug to be fixed in this
version and I'll have a look at it...
TIA

Comment 6 Eclipse Genie

2020-04-29 19:15:24 EDT

This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. As such, we're closing this bug.

If you have further information on the current state of the bug, please add it and reopen this bug. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant.

--
The automated Eclipse Genie.