[eclipse-pmc] API request: [polish] adding a sub-option for unused param

[Philippe P Mulet <philippe_mulet@xxxxxxxxxx>]

JDT/Core would like to request a new field constant addition:
JavaCore#COMPILER_PB_UNUSED_PARAMETER_INCLUDE_DOC_COMMENT_REFERENCE

This constant is identifying a new preference for better controlling the
unused parameter optional warning.
The compiler is currently detecting too many false positives when enabling
the unused parameter warning, and this got identified as a top request for
the polish effort.

Current situation is that there is no way to let the compiler know that an
apparent unused parameter is actually mandated by some API contract (for
subclasses to override).
The proposal is to allow such parameters to be documented as such, simply
by using Javadoc @param tags (i.e. if parameter is referenced from Javadoc,
then stop complaining). This behavior would be made optional, and
conditioned by this new preference.

GOALS/BENEFITS:
- allow to get rid of false positive unused parameter warnings by letting
user document these in Javadoc.

CORRESPONDING BUG(S):

https://bugs.eclipse.org/bugs/show_bug.cgi?id=118217

RISKS:

No risk, all API additions. The master preference for detecting unused
parameter is OFF by default, so the suboption has no impact by default.

PERFORMANCE IMPACTS:

No performance impact.