docs: private Node[] transformToNodes(final IndexEntry[] theIndexEntries, final Document theTargetDocument, final Comparator<IndexEntry> theIndexEntryComparator) {
          if (null != theIndexEntryComparator) {
              Arrays.sort(theIndexEntries, theIndexEntryComparator);
          }
  
          final List<Element> result = new ArrayList<Element>();
          for (final IndexEntry indexEntry : theIndexEntries) {
              final Element indexEntryNode = createElement(theTargetDocument, "index.entry");
  
              final Element formattedStringElement = createElement(theTargetDocument, "formatted-value");
              if (indexEntry.getContents() != null) {
                  for (final Iterator<Node> i = indexEntry.getContents().iterator(); i.hasNext();) {
                      final Node child = i.next();
                      final Node clone = theTargetDocument.importNode(child, true);
                      if (!i.hasNext() && clone.getNodeType() == Node.TEXT_NODE) {
                          final Text t = (Text) clone;
                          t.setData(t.getData().replaceAll("[\\s\\n]+$", ""));
                      }
                      formattedStringElement.appendChild(clone);
                  }
              } else {
                  final Text textNode = theTargetDocument.createTextNode(indexEntry.getFormattedString());
                  textNode.normalize();
                  formattedStringElement.appendChild(textNode);
              }
              indexEntryNode.appendChild(formattedStringElement);
  
              final String[] refIDs = indexEntry.getRefIDs();
              for (final String refID : refIDs) {
                  final Element referenceIDElement = createElement(theTargetDocument, "refID");
                  referenceIDElement.setAttribute("indexid", hashPrefix + Integer.toString(refID.hashCode()));
                  referenceIDElement.setAttribute("value", refID);
                  indexEntryNode.appendChild(referenceIDElement);
              }
  
              final String val = indexEntry.getValue();
              if (null != val) {
                  indexEntryNode.setAttribute("value", val);
              }
  
              final String sort = indexEntry.getSortString();
              if (null != sort) {
                  indexEntryNode.setAttribute("sort-string", sort);
              }
  
              if (indexEntry.isStartingRange()) {
                  indexEntryNode.setAttribute("start-range", "true");
              } else if (indexEntry.isEndingRange()) {
                  indexEntryNode.setAttribute("end-range", "true");
              }
              if (indexEntry.isSuppressesThePageNumber()) {
                  indexEntryNode.setAttribute("no-page", "true");
              } else if (indexEntry.isRestoresPageNumber()) {
                  indexEntryNode.setAttribute("single-page", "true");
              }
  
              final IndexEntry[] childIndexEntries = indexEntry.getChildIndexEntries();
  
              final Node[] nodes = transformToNodes(childIndexEntries, theTargetDocument, theIndexEntryComparator);
  
              for (final Node node : nodes) {
                  indexEntryNode.appendChild(node);
              }
  
              final IndexEntry[] seeChildIndexEntries = indexEntry.getSeeChildIndexEntries();
              if (seeChildIndexEntries != null) {
                  final Element seeElement = createElement(theTargetDocument, "see-childs");
                  final Node[] seeNodes = transformToNodes(seeChildIndexEntries, theTargetDocument, theIndexEntryComparator);
                  for (final Node node : seeNodes) {
                      seeElement.appendChild(node);
                  }
  
                  indexEntryNode.appendChild(seeElement);
              }
  
              final IndexEntry[] seeAlsoChildIndexEntries = indexEntry.getSeeAlsoChildIndexEntries();
              if (seeAlsoChildIndexEntries != null) {
                  final Element seeAlsoElement = createElement(theTargetDocument, "see-also-childs");
                  final Node[] seeAlsoNodes = transformToNodes(seeAlsoChildIndexEntries, theTargetDocument, theIndexEntryComparator);
                  for (final Node node : seeAlsoNodes) {
                      seeAlsoElement.appendChild(node);
                  }
  
                  indexEntryNode.appendChild(seeAlsoElement);
              }
  
              result.add(indexEntryNode);
          }
          return (Node[]) result.toArray(new Node[result.size()]);
      }