On Tue, 9 Nov 2021 08:59:32 GMT, Hendrik Schreiber <[email protected]>
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
