Provide better explanation and examples to consecutive collectors

[rsynek]

The section describing consecutive collectors is missing examples to show what data the collectors form in the stream.

Proposal:
Prepare an example data and an illustration for both consecutiveSequences and connectedRanges to clearly show how the data are sorted and how they form sequences and connected ranges.
Show the individual tuples based on this example data.

[triceo]

@TomCools Would this be something you'd be interested in looking into?

[TomCools]

Jup, will do.

[TomCools]

I had made a diagram for Consecutive Sequences, but after looking at it, half of it is filled with the "join" part before the actual explanation. So I started looking at the code and am wondering if that join should be there at all in the documentation.

Constraint multipleConsecutiveHomeMatches(ConstraintFactory constraintFactory) {
        return constraintFactory.forEach(Match.class)
                .join(Team.class, equal(Match::getHomeTeam, Function.identity()))
                .groupBy((match, team) -> team,
                        ConstraintCollectors.toConsecutiveSequences((match, team) -> match.getRound(), Round::getIndex))
                .flattenLast(SequenceChain::getConsecutiveSequences)
                .filter((team, matches) -> matches.getCount() >= MAX_CONSECUTIVE_MATCHES)
                .penalize(HardSoftScore.ONE_HARD, (team, matches) -> matches.getCount())
                .asConstraint("4 or more consecutive home matches");
}

Wouldn't this also work and take away some of the cognitive load when discussing this topic? Or am I missing nuance?
I tried it with the Sport League quickstart and the below also seems to work.

Constraint multipleConsecutiveHomeMatches(ConstraintFactory constraintFactory) {
    return constraintFactory.forEach(Match.class)
            .groupBy(Match::getHomeTeam, ConstraintCollectors.toConsecutiveSequences(m -> m.getRound().getIndex()))
            .flattenLast(SequenceChain::getConsecutiveSequences)
            .filter((homeTeam, matchSequence) -> matchSequence.getCount() >= MAX_CONSECUTIVE_MATCHES)
            .penalize(HardSoftScore.ONE_HARD, (team, matches) -> matches.getCount())
            .asConstraint("4 or more consecutive home matches");
}

[Christopher-Chianelli]

I had made a diagram for Consecutive Sequences, but after looking at it, half of it is filled with the "join" part before the actual explanation. So I started looking at the code and am wondering if that join should be there at all in the documentation.

The "join" can be removed; the team can be directly accessed from Match

[TomCools]

Thought as much, will include that when I create the PR for the diagram.