Add diagnostic output to HtmlDecorator if AJ-Doc generation fails

HtmlDecorator.decorateHTMLFile is where after Java version upgrades
(i.e. also new Javadoc generator version) usually tests fail for the
first time during builds because strings no longer match as expected.

There now is this log message on stdOut: "Something unexpected went
wrong in HtmlDecorator. Here is the full file causing the problem:"
After that, a full HTML page is logged. I hope this helps me identify
the new error on GitHub Linux Java 16, because the same test works on
Windows and I have no idea how to remote-debug a GitHub CI build.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

2 files changed, 14 insertions, 0 deletions

diff --git a/ajdoc/src/main/java/org/aspectj/tools/ajdoc/HtmlDecorator.java b/ajdoc/src/main/java/org/aspectj/tools/ajdoc/HtmlDecorator.java
index 0c519f0eb..17dcaab9c 100644
--- a/ajdoc/src/main/java/org/aspectj/tools/ajdoc/HtmlDecorator.java
+++ b/ajdoc/src/main/java/org/aspectj/tools/ajdoc/HtmlDecorator.java
@@ -277,6 +277,18 @@ class HtmlDecorator {
 					// Java7 (464604): <pre>public class <span class="strong">Azpect</span>
 					classStartIndex = fileContents.toString().indexOf("class <span class=\"" + TYPE_NAME_LABEL + "\">");
 					int classEndIndex = fileContents.toString().indexOf("</span>", classStartIndex);
+
+					// This is where after Java version upgrades usually tests fail or the first time.
+					// Logging context information helps fixing the issue quickly.
+					if (classStartIndex == -1 || classEndIndex == -1) {
+						System.out.println(
+							"Something unexpected went wrong in HtmlDecorator. Here is the full file causing the problem:\n\n" +
+								"------------------------------------------------------------------------\n\n" +
+								contents + "\n" +
+								"------------------------------------------------------------------------\n"
+						);
+					}
+
 					if (classEndIndex != -1) {
 						// Convert it to "aspect <span class="TYPE_NAME_LABEL">ClassA.InnerAspect</span>"
 						String aspectLine = "aspect" + fileContents.substring(classStartIndex + 5, classEndIndex);
diff --git a/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java b/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java
index 548f87f34..1375175a9 100644
--- a/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java
+++ b/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java
@@ -148,6 +148,8 @@ public class Main implements Config {
 			System.out.println("> Finished.");
 		} catch (Throwable e) {
 			handleInternalError(e);
+			// TODO: Is this really necessary? Why not just re-throw the exception after logging the error message?
+			//       This interrupts tests, making them exit hard, eg. stopping a whole Maven build somewhere in the middle.
 			exit(-2);
 		}
 	}