docs: static ContentMatcher createMatcher(
      OrdinalPosition lastOrdinalPosition,
      Conjunction selector,
      ContentMatcher oldMatcher)
    {
      if (tc.isEntryEnabled())
        tc.entry(
          cclass,
          "createMatcher",
          "lastOrdinalPosition: "
            + lastOrdinalPosition
            + ",selector: "
            + selector
            + ", oldmatcher: "
            + oldMatcher);
  
      // If oldMatcher is not null and is a DifficultMatcher, the new Matcher must be
      // created under it, so we just return it.
  
      if (oldMatcher instanceof DifficultMatcher)
      {
        if (tc.isDebugEnabled())
          tc.debug(
            cclass,
            "createMatcher",
            "Reusing old DifficultMatcher with position: "
              + oldMatcher.ordinalPosition
              + " for position "
              + lastOrdinalPosition);
        if (tc.isEntryEnabled())
          tc.exit(cclass, "createMatcher");
        return oldMatcher;
      }
  
      // If any SimpleTests are supplied, we find the SimpleTest (if any) whose
      // ordinalPosition is the least one greater than lastOrdinalPosition.  This gives us
      // the Identifier that is the next to be considered.  Note that oldMatcher's
      // ordinalPosition cannot be less than lastOrdinalPosition.
  
      if (oldMatcher != null && oldMatcher.ordinalPosition.compareTo(lastOrdinalPosition) < 0)
        throw new IllegalStateException();
      if (selector != null)
        for (int i = 0; i < selector.getSimpleTests().length; i++)
        {
          OrdinalPosition newPos = (OrdinalPosition) selector.getSimpleTests()[i].getIdentifier().getOrdinalPosition();
  
          if (oldMatcher != null && newPos.compareTo(oldMatcher.ordinalPosition) >= 0)
          {
            // (hence newPos > lastOrdinalPosition as well).  No new Matcher should be
            // created now because oldMatcher is either the Matcher we want or the new one
            // should be created somewhere under it.
  
            if (tc.isDebugEnabled())
              tc.debug(
                cclass,
                "createMatcher",
                "Reusing "
                  + oldMatcher.getClass().getName()
                  + " for position: "
                  + lastOrdinalPosition
                  + "; next test is at: "
                  + newPos);
            if (tc.isEntryEnabled())
              tc.exit(cclass, "createMatcher");
            return oldMatcher;
          }
  
          if (newPos.compareTo(lastOrdinalPosition) > 0)
          {
            // (but newPos < oldMatcher.ordinalPosition if oldMatcher exists at all).  A new
            // Matcher must be created and oldMatcher becomes its vacantChild.
  
            if (tc.isDebugEnabled())
              tc.debug(
                cclass,
                "createMatcher",
                "Creating new matcher at position " + newPos);
            if (tc.isEntryEnabled())
              tc.exit(cclass, "createMatcher");
            return createMatcher(selector.getSimpleTests()[i], oldMatcher);
          }
        }
  
      // If no SimpleTests were supplied or there are none whose ordinalPosition is beyond
      // lastOrdinalPosition, we must return a DifficultMatcher.  We already know that
      // oldMatcher is not a DifficultMatcher (or we wouldn't have gotten this far), so the
      // new one must be interposed ahead of oldMatcher.
  
      ContentMatcher ans = new DifficultMatcher(lastOrdinalPosition);
  
      if (tc.isDebugEnabled())
      {
        if (oldMatcher != null)
          tc.debug(
            cclass,
            "createMatcher",
            "New DifficultMatcher at position "
              + lastOrdinalPosition
              + " with successor "
              + oldMatcher.getClass().getName()
              + " at position "
              + oldMatcher.ordinalPosition);
        else
          tc.debug(
            cclass,
            "createMatcher",
            "New DifficultMatcher at position "
              + lastOrdinalPosition
              + " with null successor.");
      }
  
      ans.vacantChild = oldMatcher;
  
      if (tc.isEntryEnabled())
        tc.exit(cclass, "createMatcher");
      return ans;
    }