[eclipse-pmc] Add new API constants org.eclipse.jdt.core.formatter.CodeF

[Frederic Fusier <frederic_fusier@xxxxxxxxxx>]

GOALS/BENEFITS:
- Add a new formatter flag to request comment formatting in one pass.
  Some context:
    The current formatter does not include comments while formatting
    a compilation unit. As a consequence, for clients using this API
    (like JDT/Text), the complete formatting of a compilation unit
    code and comments currently involves multiple passes where the
formatter
    is called again for each individual block of comments.
    This not only makes it hard for clients of this API to understand
what's the
    expected behavior should be, but it is also completely inefficient on
the
    performance side.
    With the planned work, entire unit will be formatted in just one pass
    (code + comment). This feature will also be accessible to the
command-line
    formatter which up until now is unable to process comments.

- The flag API addition is intended to improve the backward compatibility
of
  the enhanced formatter.

AFFECTED BUGS:
- https://bugs.eclipse.org/bugs/show_bug.cgi?id=102780

RISKS:
- If we did not add a new flag, then we would have to retrofit the new
comment
  formatting behavior in some existing formatting mode. Though feasible,
this could
  impact some clients in non trivial ways.

- The new feature and new API has a large number of regression tests:
  -> we have added more than 200 tests on JDT/Core formatter tests
  -> comparison with current formatter on JUnit 3.8.2 sources
  -> format all units of a Ganymede M5 full source workspace (around
26,000)
     without any serious issues or loss of information

PERFORMANCE IMPACTS:
- Great performance improvements can be expected: to format a compilation
unit,
  only a single (instead of two) pass will be necessary.

Cordialement/Regards,

Frédéric