private Annotations addAnnotation(int from, int to, AnnotationClass clazz) {
        if (equalsRange(from, to)) {
            // We simply add everything from the new span to this
            if (annotations.containsKey(clazz)) {
                return annotations.get(clazz);
            } else {
                Annotations nAnnotations = new Annotations(this);
                annotations.put(clazz,nAnnotations);
                return nAnnotations;
            }
        }

        // We then check if any of the children intersects
        for (Span subSpan : getSubSpans()) {
            if (subSpan.intersects(from, to)) {
                throw new RuntimeException("Trying to add span that intersects already excisting span");
            } else if (subSpan.contains(from, to)) {
                return subSpan.addAnnotation(from, to, clazz);
            }
        }

        // We now know that we have to add the new span to this span
        Span span = new Span(from, to, this);
        Annotations nAnnotations = new Annotations(span);
        span.annotations.put(clazz,nAnnotations);
        addSubSpan(span);

        // We then add any subannotation that is inside the span
        Iterator<Span> subIterator = getRemovableSubSpan().iterator();

        while (subIterator.hasNext()) {
            Span subSpan = subIterator.next();
            if (subSpan.contains(from, to)) {
                return subSpan.addAnnotation(from, to, clazz);
            } else if (subSpan.isInside(from, to)) {
                // Take over the subannotation
                subSpan.parent = span;
                span.addSubSpan(subSpan);
                subIterator.remove();
            }
        }
        return nAnnotations;
    }
How this works:

First we check if any excisting subannotation can contain this annotation. If so, we leave it to them to add
the new annotation.

Then we check if the new annotation intersects any of the excisting annotations. That is illegal to do

We then add all subannotations that are strictly contained in the new annotation to the new annotation.
container-search/src/main/java/com/yahoo/text/interpretation/Span.java