RFR: 8276700: Improve java.lang.ref.Cleaner javadocs

[Anthony Vanelverdinghe]

On Tue, 9 Nov 2021 08:59:32 GMT, Hendrik Schreiber <hschreiber at openjdk.org> wrote:

>> The new example Cleaner instance _is_ shared, though on a pretty small scale (just among instances of CleaningExample).  A demonstration of larger scale sharing of a Cleaner instance would be out of scope for this example.
>
> Let me add, why I have raised this issue.
> 
> I was going to migrate some older code which uses the `finalize()` method to the `Cleaner` mechanism. New it it, there seemed to be two pitfalls:
> 
> 1. Understanding the whole "don't capture an instance reference in your state object"
> 2. Copying the example (which was in a non-working state, due to pseudo code) and making it work for me
> 
> With the improvement suggestions, I was trying help people who *only* read the code sample (many do), to become aware of 1. and help them getting going with 2, simply because it's something they can copy and run.

> When I see `<cleaner>`, I'm just wondering what those <> type operators are good for here...

What about just replacing `<cleaner>` with `...` then? The `State` constructor and its invocation also have an ellipsis.

> BUT, at least it's a working example and not some pseudo code.

The example is still not compilable due to the remaining ellipses.

> We do want to move to working example code long term, don't we?

I agree that examples should be compilable *in the raw Javadoc*. However, in the rendered Javadoc, using ellipses is a well-understood way to keep examples concise and devoid of irrelevant and/or usecase-dependent code. Moreover, when developers copy-paste the example, they'll immediately be pointed to all the places where they need to fill in the blanks, make a choice for a trade-off, etc. On the other hand, by hard-coding a (suboptimal) choice, developers who merely copy-paste the example are unlikely to reconsider the trade-off.

> The new example Cleaner instance _is_ shared, though on a pretty small scale (just among instances of CleaningExample).

True, but my point was that the comment says "shared *within a library*". So to me it's confusing to have a comment saying "it's preferred to do A", and then have the code do B on the next line.

So I propose to either:
* revert the current change & simply replace `<cleaner>` with `...`
* update the comment to say: "A cleaner (preferably one shared within a library, but for the sake of example, a new one is created here)"

Actually, to have the line be compilable, and at the same time (attempt to) force developers to consider the trade-off, it could be changed to something like:


private static final Cleaner cleaner = createCleaner();

private static Cleaner createCleaner() {
    // A cleaner, preferably one shared within a library
    throw new UnsupportedOperationException("TBD");
}

-------------

PR: https://git.openjdk.java.net/jdk/pull/6076