OPENNLP-1888 Discussion thread: 3.0 and API suggestion and documentation note

[Kristian Rickert]

Two main points:

  - OPENNLP-1888 has not been started; it was created as a design
discussion regarding a generic document shape I'm recommending.  Details in
the ticket
  - Thank you everyone for the detailed feedback. I'll ensure every PR has
a section in the documentation.

OPENNLP-1888 was opened to discuss a generic Document type for the new API
interface. Details are in the ticket, but here is the initial shape and I
would like anyone's thoughts on it:

public interface Document {
  CharSequence text();                            // the original text,
never a normalized form
  <T> List<Annotation<T>> get(LayerKey<T> layer); // empty list when the
layer is absent
  Set<LayerKey<?>> layers();
}

public record Annotation<T>(Span span, T value) { }

public final class LayerKey<T> {
  public static <T> LayerKey<T> of(String id, Class<T> type) { ... }
}

public interface DocumentAnnotator {
  Document annotate(Document document);           // returns a new document
with layers added
  Set<LayerKey<?>> requires();
  Set<LayerKey<?>> provides();
}