Implement suggestions from PR review

doxia-core/src/main/java/org/apache/maven/doxia/index/IndexEntry.java

@@ -53,6 +53,9 @@ public class IndexEntry {
      */
     private List<IndexEntry> childEntries = new ArrayList<>();
 
+    /** The type of the entry, one of the types defined by {@link IndexingSink} */
+    private int type;
+
     /**
      * System-dependent EOL.
      */
@@ -74,12 +77,23 @@ public IndexEntry(String newId) {
      * @param newId     The id. May be null.
      */
     public IndexEntry(IndexEntry newParent, String newId) {
+        this(newParent, newId, 0);
+    }
+
+    /**
+     * Constructor.
+     *
+     * @param newParent The parent. May be null.
+     * @param newId     The id. May be null.
+     */
+    public IndexEntry(IndexEntry newParent, String newId, int type) {
         this.parent = newParent;
         this.id = newId;
 
         if (parent != null) {
             parent.childEntries.add(this);
         }
+        this.type = type;
     }
 
     /**
@@ -110,6 +124,21 @@ protected void setId(String id) {
         this.id = id;
     }
 
+    /** Set if the entry's id already has an anchor in the underlying document.
+     *
+     * @param hasAnchor {@true} if the id already has an anchor.
+     * @since 2.0.0
+     */
+    public void setAnchor(boolean hasAnchor) {
+        this.hasAnchor = hasAnchor;
+    }
+
+    /**
+     * Returns if the entry's id already has an anchor in the underlying document.
+     * @return {@code true} if the id already has an anchor otherwise {@code false}.
+     *
+     * @since 2.0.0
+     */
     public boolean hasAnchor() {
         return hasAnchor;
     }

doxia-core/src/main/java/org/apache/maven/doxia/index/IndexingSink.java

@@ -32,7 +32,8 @@
 import org.apache.maven.doxia.util.DoxiaUtils;
 
 /**
- * A sink wrapper for populating a section index.
+ * A sink wrapper for populating an index tree for particular elements in a document.
+ * Currently this only generates {@link IndexEntry} objects for sections.
  *
  * @author <a href="mailto:trygvis@inamo.no">Trygve Laugst&oslash;l</a>
  * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
@@ -82,6 +83,7 @@ public class IndexingSink extends SinkWrapper {
 
     private final IndexEntry rootEntry;
 
+    private boolean isComplete;
     /**
      * @deprecated legacy constructor, use {@link #IndexingSink(Sink)} with {@link SinkAdapter} as argument and call {@link #getRootEntry()} to retrieve the index tree afterwards.
      */
@@ -104,15 +106,21 @@ private IndexingSink(IndexEntry rootEntry, Sink delegate) {
         stack.push(rootEntry);
         usedIds = new HashMap<>();
         usedIds.put(rootEntry.getId(), new AtomicInteger());
-        init();
+        this.type = 0;
+        this.title = null;
     }
 
     /**
      * This should only be called once the sink is closed.
      * Before that the tree might not be complete.
      * @return the tree of entries starting from the root
+     * @throws IllegalStateException in case the sink was not closed yet
      */
     public IndexEntry getRootEntry() {
+        if (!isComplete) {
+            throw new IllegalStateException(
+                    "The sink has not been closed yet, i.e. the index tree is not complete yet");
+        }
         return rootEntry;
     }
     /**
@@ -228,6 +236,7 @@ private boolean parseAnchor(String name) {
             case TYPE_SECTION_4:
             case TYPE_SECTION_5:
                 IndexEntry entry = stack.lastElement();
+                entry.setAnchor(true);
                 setEntryId(entry, name);
                 break;
             default:
@@ -321,13 +330,6 @@ public IndexEntry peek() {
     @Override
     public void close() {
         super.close();
-
-        init();
-    }
-
-    @Override
-    protected void init() {
-        this.type = 0;
-        this.title = null;
+        isComplete = true;
     }
 }

doxia-core/src/main/java/org/apache/maven/doxia/macro/toc/TocMacro.java

@@ -104,11 +104,12 @@ public void execute(Sink sink, MacroRequest request) throws MacroExecutionExcept
         }
 
         IndexingSink tocSink = new IndexingSink(new SinkAdapter());
-
         try {
             parser.parse(new StringReader(source), tocSink);
         } catch (ParseException e) {
             throw new MacroExecutionException(e);
+        } finally {
+            tocSink.close();
         }
 
         IndexEntry index = tocSink.getRootEntry();

doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java

@@ -230,7 +230,7 @@ protected boolean isSecondParsing() {
     }
 
     @Override
-    public void registerSinkWrapperFactory(SinkWrapperFactory factory) {
+    public void addSinkWrapperFactory(SinkWrapperFactory factory) {
         manuallyRegisteredSinkWrapperFactories.add(factory);
     }
 

doxia-core/src/main/java/org/apache/maven/doxia/parser/BufferingSinkProxyFactory.java

@@ -106,7 +106,7 @@ public static BufferingSink castAsBufferingSink(Sink sink) {
     }
 
     @Override
-    public int getRank() {
+    public int getPriority() {
         return 0;
     }
 }

doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java

@@ -91,7 +91,7 @@ public interface Parser {
      * @param factory the factory to create the sink wrapper
      * @since 2.0.0
      */
-    void registerSinkWrapperFactory(SinkWrapperFactory factory);
+    void addSinkWrapperFactory(SinkWrapperFactory factory);
 
     /**
      *
@@ -101,7 +101,7 @@ public interface Parser {
     Collection<SinkWrapperFactory> getSinkWrapperFactories();
 
     /**
-     * Determines whether to automatically generate anchors for each section found by {@link IndexingSink} or not.
+     * Determines whether to automatically generate anchors for each index entry found by {@link IndexingSink} or not.
      * By default no anchors are generated.
      *
      * @param emitAnchors {@code true} to emit anchors otherwise {@code false} (the default)
@@ -110,7 +110,7 @@ public interface Parser {
     void setEmitAnchors(boolean emitAnchors);
 
     /**
-     * Returns whether anchors are automatically generated for each section found by {@link IndexingSink} or not.
+     * Returns whether anchors are automatically generated for each index entry found by {@link IndexingSink} or not.
      * @return  {@code true} if anchors are emitted otherwise {@code false}
      * @since 2.0.0
      */

doxia-core/src/main/java/org/apache/maven/doxia/parser/SinkWrapperFactory.java

@@ -36,8 +36,8 @@ public interface SinkWrapperFactory {
     Sink createWrapper(Sink sink);
 
     /**
-     * Determines the order of sink wrappers. The highest ranked wrapper factory is called first.
-     * @return the rank of this factory
+     * Determines the order of sink wrappers. The wrapper factory with the highest priority is called first.
+     * @return the priority of this factory
      */
-    int getRank();
+    int getPriority();
 }

doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/CreateAnchorsForIndexEntriesFactory.java

@@ -33,7 +33,7 @@ public Sink createWrapper(Sink sink) {
     }
 
     @Override
-    public int getRank() {
+    public int getPriority() {
         return 0;
     }
 }

doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapperFactoryComparator.java

@@ -28,6 +28,6 @@ public class SinkWrapperFactoryComparator implements Comparator<SinkWrapperFacto
     @Override
     public int compare(SinkWrapperFactory o1, SinkWrapperFactory o2) {
 
-        return Integer.compare(o2.getRank(), o1.getRank());
+        return Integer.compare(o2.getPriority(), o1.getPriority());
     }
 }

doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/UniqueAnchorNamesValidatorFactory.java

@@ -32,7 +32,7 @@ public Sink createWrapper(Sink sink) {
     }
 
     @Override
-    public int getRank() {
+    public int getPriority() {
         // should come last (after potential preprocessing/modification of anchor names)
         return -1000;
     }

doxia-core/src/test/java/org/apache/maven/doxia/macro/toc/TocMacroTest.java

@@ -195,7 +195,7 @@ public void testGenerateAnchors() throws ParseException, MacroExecutionException
         // check html output as well (without the actual TOC)
         StringWriter out = new StringWriter();
         Sink sink2 = new Xhtml5BaseSink(out);
-        parser.registerSinkWrapperFactory(new CreateAnchorsForIndexEntriesFactory());
+        parser.addSinkWrapperFactory(new CreateAnchorsForIndexEntriesFactory());
         parser.parse(sourceContent, sink2);
         assertEquals(
                 "<section><a id=\"" + actualLinkTarget.substring(1) + "\"></a>\n" + "<h1>1 Headline</h1>",

doxia-core/src/test/java/org/apache/maven/doxia/parser/AbstractParserTest.java

@@ -102,7 +102,7 @@ public final void testDocument() throws IOException, ParseException {
     public final void testSinkWrapper() throws ParseException, IOException {
         Parser parser = createParser();
 
-        parser.registerSinkWrapperFactory(new SinkWrapperFactory() {
+        parser.addSinkWrapperFactory(new SinkWrapperFactory() {
 
             @Override
             public Sink createWrapper(Sink sink) {
@@ -116,12 +116,12 @@ public void text(String text, SinkEventAttributes attributes) {
             }
 
             @Override
-            public int getRank() {
+            public int getPriority() {
                 return 0;
             }
         });
 
-        parser.registerSinkWrapperFactory(new SinkWrapperFactory() {
+        parser.addSinkWrapperFactory(new SinkWrapperFactory() {
 
             @Override
             public Sink createWrapper(Sink sink) {
@@ -134,7 +134,7 @@ public void text(String text, SinkEventAttributes attributes) {
             }
 
             @Override
-            public int getRank() {
+            public int getPriority() {
                 return 1;
             }
         });