eclipse / eclipse-collections

Eclipse Collections is a collections framework for Java with optimized data structures and a rich, functional and fluent API.
https://eclipse.dev/collections/
2.42k stars 604 forks source link

Reference Guide: Code blocks chapter introduction describes code blocks as single-abstract-method objects (and more) #1498

Open Chealer opened 1 year ago

Chealer commented 1 year ago

Chapter Code Blocks of the reference guide contains a few issues. I'm taking the liberty to report those I spotted here, but feel free to mark this as resolved once the first has been addressed. The section opens with:

A code block, in Eclipse Collections terms, is a single-abstract-method object that is passed as a parameter to an iteration method. It is an abstraction that represents the evaluation of each element in the course of iteration.

The first sentence is incorrect. Objects cannot have abstract methods. Classes/interfaces can. I suppose this should rather say code blocks are functional objects.

The second sentence is also incorrect, probably focused on predicates. Elements are not necessarily evaluated. I suggest replacing it with:

A code block specifies how iteration should process each element.

The following sentence seems misleading to me and it might be best to improve or remove it:

What we call a "code block" in Eclipse Collections is roughly analogous to a lambda expression.

Finally, the last paragraph (in the table's right cell) contains this:

For the limited purposes of this guide—and in particular the scope of this topic—we use parameter to specify the input to an iteration method, such as select(). These parameters can take the form of a code block, (implementing Predicate) which itself is an object with methods.

The implication that code blocks necessarily implement Predicate is wrong. A code block which implements Function, for example, does not have to implement Predicate.