Bug 322581 - [5.0] Add Javadoc compiler option to (not) report missing tags for method type parameters
Summary: [5.0] Add Javadoc compiler option to (not) report missing tags for method typ...
Status: VERIFIED FIXED
Alias: None
Product: JDT
Classification: Eclipse Project
Component: Core (show other bugs)
Version: 3.7   Edit
Hardware: PC Windows XP
: P3 enhancement (vote)
Target Milestone: 3.7 M3   Edit
Assignee: Ayushman Jain CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks: 327022
  Show dependency tree
 
Reported: 2010-08-12 15:48 EDT by Markus Keller CLA
Modified: 2010-10-26 04:36 EDT (History)
3 users (show)

See Also:
markus.kell.r: review+

Attachments
test project (1.73 KB, application/zip)
2010-08-16 13:25 EDT, Markus Keller CLA 		no flags Details
proposed fix v1.0 + regression tests (15.16 KB, patch)
2010-09-29 13:01 EDT, Ayushman Jain CLA 		no flags Details | Diff
released patch (15.15 KB, patch)
2010-10-06 10:00 EDT, Ayushman Jain CLA 		no flags Details | Diff
Show Obsolete (1) View All Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
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