From e9f0c04940d7c8dfb4a094fad12973f51d815fae Mon Sep 17 00:00:00 2001
From: Dan Allen <dan@opendevise.com>
Date: Tue, 14 May 2024 12:48:52 -0600
Subject: [PATCH] add documentation for the jetty block extension

---
 lib/jetty-block.js | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/lib/jetty-block.js b/lib/jetty-block.js
index 6c47316..854fcdd 100644
--- a/lib/jetty-block.js
+++ b/lib/jetty-block.js
@@ -10,6 +10,39 @@ const MAIN_CLASS = {
   10: 'org.eclipse.jetty.tests.hometester.RunJetty',
 }
 
+/**
+ * This extension introduces a custom literal block named jetty to the AsciiDoc syntax.
+ *
+ * Usage:
+ *
+ * [jetty%nowrap]
+ * ....
+ * [jetty]
+ * setupModules=code:example$jetty-modules/jvm.mod,code:example$jetty-modules/postgresql.mod
+ * setupArgs=--add-modules=server,http,postgresql,jvm
+ * args=--list-config
+ * ....
+ *
+ * When this block is encountered, the contents are passed to the RunJetty class provided by the
+ * Jetty project. This main class sets up Jetty and runs it with the specified parameters. The
+ * extension then captures the filtered output from that main class and uses it as the contents of a
+ * new literal block, which it then returns. Any options set on the jetty block (e.g., %nowrap) will
+ * be passed through to this new block.
+ *
+ * The contents of the jetty block must be sequential lines of key=value pairs with an optional
+ * [jetty] opening line for labeling. The supported keys are as follows: setupModules, setupArgs,
+ * args, and highlight. The setupModules key is used to enable additional Jetty modules before
+ * running Jetty. The setupArgs keys is used to run Jetty before capturing the output. The args key
+ * is used to run Jetty when capturing the output. The highlight key is used to apply AsciiDoc
+ * formatting to the output. AsciiDoc attribute references are permitted in the value of any key.
+ *
+ * This extension will only process the contents of the jetty block if the jetty-home attribute
+ * points to a Jetty home directory and the run-jetty-classpath attribute contains a valid classpath
+ * for running the RunJetty main class. If these attributes are not set appropriately, the extension
+ * will return a plain literal block. This is where the optional [jetty] label comes in handy.
+ *
+ * To print the RunJetty command, run Antora with the logging level set to info.
+ */
 function createExtensionGroup (context) {
   return function () {
     let jettyHome, runJettyClasspath