Address review feedback on footnotes - javadocs
Update javadocs as per feedback
some docs are more useful on getter than class
reword note on catalog being internal
mention that Footnote.getIndex() is 1 based
And am now better describing Footnote class getters in general.
MODIFY
asciidoctorj-api/src/main/java/org/asciidoctor/ast/Catalog.java
asciidoctorj-api/src/main/java/org/asciidoctor/ast/Catalog.java
@@ -2,15 +2,11 @@ package org.asciidoctor.ast;
import java.util.List;
-/**
- * The asciidoctor catalog contains data collected by asciidoctor that is useful to a converter.
- * The catalog is considered an internal structure by asciidoctor, and subject to change.
- */
+
public interface Catalog {
/**
- * Note that asciidoctor does not populate footnotes until after the
- * Document's content has been converted.
+ * Note that footnotes are only available after `Document.getContent()` has been called.
*
* @return footnotes occurring in document.
*/

MODIFY
asciidoctorj-api/src/main/java/org/asciidoctor/ast/Document.java
asciidoctorj-api/src/main/java/org/asciidoctor/ast/Document.java
@@ -77,5 +77,12 @@ public interface Document extends StructuralNode {
void setSourcemap(boolean state);
+ /**
+ * The catalog contains data collected by asciidoctor that is useful to a converter.
+ *
+ * Note that the catalog is not part of the asciidoctor public API and is subject to change.
+ *
+ * @return catalog
+ */
Catalog getCatalog();
}

MODIFY
asciidoctorj-api/src/main/java/org/asciidoctor/ast/Footnote.java
asciidoctorj-api/src/main/java/org/asciidoctor/ast/Footnote.java
@@ -2,9 +2,24 @@ package org.asciidoctor.ast;
public interface Footnote {
+ /**
+ * The index is the number asciidoctor has assigned to the footnote.
+ * Footnotes start at 1 and are numbered consecutively throughout the document.
+ *
+ * @return footnote number
+ */
Long getIndex();
+ /**
+ * Each footnote can optionally have an id.
+ * Ids are used when a document author wants to reference a single footnote more than once.
+ *
+ * @return footnote id or null
+ */
String getId();
+ /**
+ * @return the text the document author has specified for the footnote
+ */
String getText();
}

Address review feedback on footnotes - javadocs

Update javadocs as per feedback
- some docs are more useful on getter than class
- reword note on catalog being internal
- mention that Footnote.getIndex() is 1 based

And am now better describing Footnote class getters in general.