Skip to content

Add annotation processor to generate documentation #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Feb 9, 2024
Merged

Add annotation processor to generate documentation #102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a68c9dd
Add annotation processor to generate documentation
ppkarwasz Feb 2, 2024
ccab8f5
Review fixes for #102
ppkarwasz Feb 8, 2024
1cd484a
Remove dependency on annotation classes
ppkarwasz Feb 9, 2024
8abc774
Downgrade Java version to 11.
ppkarwasz Feb 9, 2024
0e7a34e
Add test for 2.x annotations
ppkarwasz Feb 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 38 additions & 8 deletions log4j-docgen/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,21 +27,36 @@
<artifactId>log4j-docgen</artifactId>

<properties>
<maven.compiler.release>17</maven.compiler.release>
<maven.compiler.release>11</maven.compiler.release>
<bnd.baseline.fail.on.missing>false</bnd.baseline.fail.on.missing>

<!-- Dependency versions -->
<asciidoctorj-api.version>3.0.0-alpha.2</asciidoctorj-api.version>
<!-- We explicitly test against `log4j-core` 2.x -->
<log4j-core.version>2.22.1</log4j-core.version>
<log4j-plugins.version>3.0.0-beta1</log4j-plugins.version>
</properties>

<dependencies>

<dependency>
<groupId>biz.aQute.bnd</groupId>
<artifactId>biz.aQute.bnd.annotation</artifactId>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>jakarta.inject</groupId>
<artifactId>jakarta.inject-api</artifactId>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>org.jspecify</groupId>
<artifactId>jspecify</artifactId>
<scope>provided</scope>
</dependency>

<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-api</artifactId>
Expand All @@ -59,13 +74,28 @@
</dependency>

<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-plugins</artifactId>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<artifactId>junit-jupiter-params</artifactId>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<version>${log4j-core.version}</version>
<scope>test</scope>
</dependency>

<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-plugins</artifactId>
<version>${log4j-plugins.version}</version>
<scope>test</scope>
</dependency>

Expand All @@ -80,14 +110,14 @@
<build>
<plugins>

<!--
~ We split compilation in two executions, so we can fail on warnings for our sources,
~ but be more tolerant for generated sources.
-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<!--
~ We split compilation in two executions, so we can fail on warnings for our sources,
~ but be more tolerant for generated sources.
-->
<execution>
<id>default-compile</id>
<phase>none</phase>
Expand Down
18 changes: 10 additions & 8 deletions ...docgen/src/main/java/org/apache/logging/log4j/docgen/internal/DefaultSchemaGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@
import java.util.Collection;
import java.util.List;
import java.util.Set;
import java.util.TreeSet;
import javax.inject.Named;
import javax.inject.Singleton;
import javax.xml.XMLConstants;
Expand Down Expand Up @@ -190,15 +189,13 @@ private static void writeAbstractType(
}
writer.writeStartElement(XSD_NAMESPACE, "choice");

final Set<String> implementations = new TreeSet<>(abstractType.getImplementations());
final Set<String> implementations = abstractType.getImplementations();
if (abstractType instanceof PluginType) {
implementations.add(abstractType.getClassName());
}
for (final String implementation : implementations) {
final PluginType pluginType = (PluginType) lookup.get(implementation);
final Collection<String> keys = new TreeSet<>(pluginType.getAliases());
keys.add(pluginType.getName());
for (final String key : keys) {
for (final String key : getKeyAndAliases(pluginType)) {
writer.writeEmptyElement(XSD_NAMESPACE, "element");
writer.writeAttribute("name", key);
writer.writeAttribute("type", LOG4J_PREFIX + ":" + pluginType.getClassName());
Expand Down Expand Up @@ -248,9 +245,7 @@ private static void writePluginElement(
writeDocumentation(element.getDescription(), writer);
writer.writeEndElement();
} else {
final Collection<String> keys = new TreeSet<>(pluginType.getAliases());
keys.add(pluginType.getName());
for (final String key : keys) {
for (final String key : getKeyAndAliases(pluginType)) {
writer.writeStartElement(XSD_NAMESPACE, "element");
writer.writeAttribute("name", key);
writer.writeAttribute("type", xmlType);
Expand Down Expand Up @@ -303,4 +298,11 @@ private static void writeMultiplicity(
writer.writeAttribute("maxOccurs", "unbounded");
}
}

private static Collection<String> getKeyAndAliases(final PluginType pluginType) {
final Collection<String> keys = new ArrayList<>();
keys.add(pluginType.getName());
keys.addAll(pluginType.getAliases());
return keys;
}
}
39 changes: 23 additions & 16 deletions .../src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciidocTreeVisitor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
*/
package org.apache.logging.log4j.docgen.processor;

import static org.apache.commons.lang3.StringUtils.isEmpty;
import static org.apache.commons.lang3.StringUtils.substringBefore;

import com.sun.source.doctree.DocTree;
Expand All @@ -25,7 +26,6 @@
import com.sun.source.doctree.LiteralTree;
import com.sun.source.doctree.StartElementTree;
import com.sun.source.doctree.TextTree;
import com.sun.source.util.DocTrees;
import com.sun.source.util.SimpleDocTreeVisitor;
import java.util.ArrayList;
import java.util.regex.Pattern;
Expand Down Expand Up @@ -59,15 +59,6 @@ abstract class AbstractAsciidocTreeVisitor extends SimpleDocTreeVisitor<Void, As
// Simple pattern to match (most) XML opening tags
private static final Pattern XML_TAG = Pattern.compile("<\\w+\\s*(\\w+=[\"'][^\"']*[\"']\\s*)*/?>");

/**
* Used to convert entities into strings.
*/
private final DocTrees docTrees;

AbstractAsciidocTreeVisitor(final DocTrees docTrees) {
this.docTrees = docTrees;
}

@Override
public Void visitStartElement(final StartElementTree node, final AsciidocData data) {
final String elementName = node.getName().toString();
Expand Down Expand Up @@ -165,7 +156,7 @@ public Void visitEndElement(final EndElementTree node, final AsciidocData data)
case "h5":
case "h6":
// Only flush the current line
if (!data.getCurrentLine().isEmpty()) {
if (!isEmpty(data.getCurrentLine())) {
data.newLine();
}
// The current paragraph contains the title
Expand Down Expand Up @@ -236,10 +227,7 @@ public Void visitEndElement(final EndElementTree node, final AsciidocData data)
public Void visitLink(final LinkTree node, final AsciidocData data) {
final String className = substringBefore(node.getReference().getSignature(), '#');
final String simpleName = StringUtils.substringAfterLast(className, '.');
if (!data.getCurrentLine().isEmpty()) {
data.append(" ");
}
data.append("xref:")
data.appendAdjustingSpace(" xref:")
.append(className)
.append(".adoc[")
.append(simpleName)
Expand All @@ -261,7 +249,26 @@ public Void visitLiteral(final LiteralTree node, final AsciidocData data) {

@Override
public Void visitEntity(final EntityTree node, final AsciidocData asciidocData) {
final String text = docTrees.getCharacters(node);
final String text;
switch (node.getName().toString()) {
case "amp":
text = "&";
break;
case "apos":
text = "'";
break;
case "gt":
text = ">";
break;
case "lt":
text = "<";
break;
case "quot":
text = "\"";
break;
default:
text = null;
}
if (text != null) {
asciidocData.append(text);
}
Expand Down
Loading