From 53acce43bc5d9bb49ea8ea8fc5166888d3ae8668 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan@opendevise.com>
Date: Fri, 20 Jan 2023 18:50:05 -0700
Subject: [PATCH] add docs to local Antora extensions

---
 .../extensions/inject-collector-config.js     | 22 +++++++++----------
 .../extensions/publish-docsearch-config.js    | 10 +++++++--
 lib/antora/extensions/version-fix.js          | 14 ++++++++++++
 3 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/lib/antora/extensions/inject-collector-config.js b/lib/antora/extensions/inject-collector-config.js
index de2e15f2ad..0ded65bd3c 100644
--- a/lib/antora/extensions/inject-collector-config.js
+++ b/lib/antora/extensions/inject-collector-config.js
@@ -5,21 +5,21 @@ const JVM_ARGS='-Xmx3g -XX:+HeapDumpOnOutOfMemoryError'
 const REPO_URL = 'https://github.com/spring-projects/spring-security'
 const TASK_NAME=':spring-security-docs:generateAntora'
 
+/**
+ * The purpose of this extension is to inject the Antora Collector configuration into the parsed component version
+ * descriptor in tags created before Antora Collector was introduced. Antora Collector runs a command to generate a
+ * replacement antora.yml that a) sets the version from the value of the version property in gradle.properties and b)
+ * populates AsciiDoc attributes with information from the Gradle build, such as software versions and resource URLs.
+ */
 module.exports.register = function () {
   this.once('contentAggregated', ({ contentAggregate }) => {
     for (const { origins } of contentAggregate) {
       for (const origin of origins) {
-        if (origin.url === REPO_URL && origin.descriptor.ext?.collector === undefined) {
-          origin.descriptor.ext = {
-            collector: {
-              run: {
-                command: `${BASE_COMMAND} "-Dorg.gradle.jvmargs=${JVM_ARGS}" ${TASK_NAME}`,
-                local: true,
-              },
-              scan: {
-                dir: './build/generateAntora',
-              },
-            }
+        if (!(origin.url === REPO_URL && origin.descriptor.ext?.collector === undefined)) continue
+        origin.descriptor.ext = {
+          collector: {
+            run: { command: `${BASE_COMMAND} "-Dorg.gradle.jvmargs=${JVM_ARGS}" ${TASK_NAME}`, local: true },
+            scan: { dir: './build/generateAntora' },
           }
         }
       }
diff --git a/lib/antora/extensions/publish-docsearch-config.js b/lib/antora/extensions/publish-docsearch-config.js
index 7a7c6fadcf..a40213e9b5 100644
--- a/lib/antora/extensions/publish-docsearch-config.js
+++ b/lib/antora/extensions/publish-docsearch-config.js
@@ -4,8 +4,14 @@ const fsp = require('node:fs/promises')
 const ospath = require('node:path')
 
 /**
- * An Antora extension that generates the docsearch config file from a Handlebars template and publishes it with the
- * site, where the scraper job can retrieve it.
+ * An Antora extension that generates a config file that controls the behavior of the docsearch scraper.
+ *
+ * This extension generates a docsearch config file by evaluating a Handlebars template (e.g.,
+ * .github/actions/docsearch-config.json.hbs). It then publishes the output file to the root of the site
+ * (docsearch-config.json). The docsearch scraper will retrieve for the config file from the published site.
+ *
+ * This extension will only add entries for the latest version in each release line. Additionally, if the page-archived
+ * or page-noindex attribute is defined in the document header of the page, that page will be excluded from the index.
  */
 module.exports.register = function ({ config: { templatePath = './docsearch/config.json.hbs' } }) {
   const expandPath = this.require('@antora/expand-path-helper')
diff --git a/lib/antora/extensions/version-fix.js b/lib/antora/extensions/version-fix.js
index eeba12e12b..7051845532 100644
--- a/lib/antora/extensions/version-fix.js
+++ b/lib/antora/extensions/version-fix.js
@@ -1,5 +1,19 @@
 'use strict'
 
+/**
+ * The purpose of this extension is to fix invalid metadata saved to either antora.yml or gradle.properties in certain
+ * tags. This invalid metadata prevents Antora from classifying the component versions properly.
+ *
+ * This extension addresses with the following cases:
+ * 
+ * . the boolean value on the prerelease key is incorrectly quoted
+ * . the prerelease tag is set to true for a GA version
+ * . the value of the name key is empty
+ * . the value of the displayVersion key doesn't match the actual version
+ * . the -SNAPSHOT suffix is appended to the value of the version key instead of the value of the prerelease key
+ *
+ * This extension should be listed directly after @antora/collector-extension.
+ */
 module.exports.register = function () {
   this.once('contentAggregated', ({ contentAggregate }) => {
     contentAggregate.forEach((componentVersionBucket) => {