Bug 322581

Summary: [5.0] Add Javadoc compiler option to (not) report missing tags for method type parameters
Product: [Eclipse Project] JDT Reporter: Markus Keller <markus.kell.r>
Component: CoreAssignee: Ayushman Jain <amj87.iitr>
Status: VERIFIED FIXED QA Contact:
Severity: enhancement    
Priority: P3 CC: amj87.iitr, daniel_megert, rthakkar
Version: 3.7Flags: markus.kell.r: review+
Target Milestone: 3.7 M3   
Hardware: PC   
OS: Windows XP   
Whiteboard:
Bug Depends on:    
Bug Blocks: 327022    
Attachments:
Description Flags
test project
none
proposed fix v1.0 + regression tests
none
released patch none

Description Markus Keller CLA 2010-08-12 15:48:12 EDT 
HEAD

Add a Javadoc compiler option to (not) report missing tags for method type parameters, e.g. COMPILER_PB_MISSING_JAVADOC_TAGS_METHOD_TYPE_PARAMETERS with default: "disabled".

In method declarations, type parameters are just placeholders and very rarely have a better description than just "type parameter". I didn't find even a single documented type parameter in the JDK.

Type parameters of types have a much broader scope, so it makes sense to document those (although they're typically boilerplate like "the type of the elements")
Comment 1 Ayushman Jain CLA 2010-08-13 03:33:56 EDT 
(In reply to comment #0)
> HEAD
> 
> Add a Javadoc compiler option to (not) report missing tags for method type
> parameters, e.g. COMPILER_PB_MISSING_JAVADOC_TAGS_METHOD_TYPE_PARAMETERS with
> default: "disabled".
> 
> In method declarations, type parameters are just placeholders and very rarely
> have a better description than just "type parameter". I didn't find even a
> single documented type parameter in the JDK.


Markus, can you please attach a testcase with the new warning as it should be when the option is enabled? Thanks!

And I believe this would be on the lines of COMPILER_PB_MISSING_JAVADOC_TAGS_OVERRIDING?
Comment 2 Markus Keller CLA 2010-08-16 13:25:02 EDT 
Created attachment 176704 [details]
test project

Here's a test project with the required Javadoc compiler settings. Note that I don't request a new warning -- I want to disable the existing warning for method type parameters.

> And I believe this would be on the lines of
> COMPILER_PB_MISSING_JAVADOC_TAGS_OVERRIDING?

Exactly.
Comment 3 Ayushman Jain CLA 2010-09-29 13:01:41 EDT 
Created attachment 179869 [details]
proposed fix v1.0 + regression tests

Fix introducing the new option JavaCore.COMPILER_PB_MISSING_JAVADOC_TAGS_METHOD_TYPE_PARAMETERS.
Also updated the jdt doc.

Markus, please review. Thanks
Comment 4 Markus Keller CLA 2010-10-05 11:36:37 EDT 
Looks mostly good and works fine.

The Javadoc of JavaCore#COMPILER_PB_MISSING_JAVADOC_TAGS_METHOD_TYPE_PARAMETERS needs 2 changes:
- Javadoc should be capitalized
- "for the type parameter" should be "for a type parameter"

Typos in jdt_api_options.htm:
- javadoc -> Javadoc
- compliance is 1.6 or greater -> 1.5
Comment 5 Ayushman Jain CLA 2010-10-06 10:00:38 EDT 
Created attachment 180330 [details]
released patch

Released in HEAD for 3.7M3.
Comment 6 Ayushman Jain CLA 2010-10-06 10:01:17 EDT 
Fixed
Comment 7 Rajesh CLA 2010-10-26 04:36:58 EDT 
Verified for 3.7M3 in I20101025-1800