RFR: JDK-8238646 Cleanup signature and use of CommentHelper

[Pavel Rappo]

> On 7 Feb 2020, at 18:05, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> On 2/7/20 9:22 AM, Pavel Rappo wrote:
>> 1. I don't know that code base well, but I'm slowly getting there. The trick
>> with this change is to make sure that all those configurations are
>> interchangeable (e.g. are the same object). Now, I understand it is*likely*  to
>> be the case. What else could there be? It's just that my eyes started hurting
>> when saw all the different ways one could get this object: utils.configuration,
>> input.utils.configuration, writer.configuration(), through method parameters,
>> etc. So I will focus on unraveling that ball of mud.
> There is only one configuration per HtmlDoclet instance, and only one HtmlDoclet
> per javadoc invocation. Remember the Highlander movies: "There can only be one".

Okay, that's what I suspected. I satisfied myself by making sure that the
configuration is created only once, that there's no way of copying it, and
that nobody seems to clone it.

> The configuration is passed around everywhere, but it should always be the same one.

Yeah, the code (not the patch) still leaves me with a feeling of unease. It's as
if the objects look around for whatever convenient neighboring objects to ad-hoc
provide the required configuration. It should be refactored, though not in this
patch.

> If you ever see evidence to the contrary, that would be a major, major bug.
> 
> -- Jon

Looks good.

-Pavel