Clarify when to expect multiple Result vs when to expect multiple Segment

[lukaseder]

Feature Request

Is your feature request related to a problem? Please describe

When executing things that produce multiple result values, it is currently unclear when to expect:

• Multiple Result values from the Statement::execute publisher
• Multiple Segment values from the various Result::flatMap and other methods

Reverse engineering the drivers (I'm still on 0.9.x, maybe this has changed), I feel we have:

• Multiple Result values
  • When running a Batch (multiple SQLs, no binds)
  • When running a ; separated statement batch in a single Statement, e.g. in SQL Server
• Multiple Segment values
  • When running a Statement with batched bind values

There may be other cases, or inconsistencies. I don't have much confidence in my above judgement.

Describe the solution you'd like

I would like to see, in the Javadoc, some clarification about:

• What the intent of the two ways of producing multiple results is, at least in the SPI
• What users can expect from drivers

[lukaseder]

Note, we've probably discussed this elsewhere in the past, but I've forgotten. Thus, it would be great if the Javadoc specified this.