Skip to content

Commit 4cbbfbd

Browse files
ppkarwaszppkarwasz
committed
Add annotation processor to generate documentation
We add a documentation-generating annotation processor. By default it generates a `plugins.xml` descriptor in the `META-INF/log4j` directory of the output folder. Currently it supports: * Log4j Plugins 3.x annotations **only**, * Both factory methods and builders. Closes apache/logging-log4j2#1956.
1 parent 6cda1cb commit 4cbbfbd

File tree

13 files changed

+1390
-4
lines changed

13 files changed

+1390
-4
lines changed

‎log4j-docgen/pom.xml

+12
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,24 @@
3636

3737
<dependencies>
3838

39+
<dependency>
40+
<groupId>biz.aQute.bnd</groupId>
41+
<artifactId>biz.aQute.bnd.annotation</artifactId>
42+
<scope>provided</scope>
43+
</dependency>
44+
3945
<dependency>
4046
<groupId>jakarta.inject</groupId>
4147
<artifactId>jakarta.inject-api</artifactId>
4248
<scope>provided</scope>
4349
</dependency>
4450

51+
<dependency>
52+
<groupId>org.jspecify</groupId>
53+
<artifactId>jspecify</artifactId>
54+
<scope>provided</scope>
55+
</dependency>
56+
4557
<dependency>
4658
<groupId>org.asciidoctor</groupId>
4759
<artifactId>asciidoctorj-api</artifactId>

‎log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/AbstractAsciidocTreeVisitor.java

+1-4
Original file line numberDiff line numberDiff line change
@@ -236,10 +236,7 @@ public Void visitEndElement(final EndElementTree node, final AsciidocData data)
236236
public Void visitLink(final LinkTree node, final AsciidocData data) {
237237
final String className = substringBefore(node.getReference().getSignature(), '#');
238238
final String simpleName = StringUtils.substringAfterLast(className, '.');
239-
if (!data.getCurrentLine().isEmpty()) {
240-
data.append(" ");
241-
}
242-
data.append("xref:")
239+
data.appendAdjustingSpace(" xref:")
243240
.append(className)
244241
.append(".adoc[")
245242
.append(simpleName)

‎log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/processor/DocGenProcessor.java

+692
Large diffs are not rendered by default.

‎log4j-docgen/src/test/it/example/AbstractAppender.java

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to you under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package example;
18+
19+
/**
20+
* An example of base abstract class.
21+
*/
22+
public abstract class AbstractAppender implements BaseAppender {
23+
}

‎log4j-docgen/src/test/it/example/Appender.java

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to you under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package example;
18+
19+
/**
20+
* Extended interface that also allows to do {@code baz}.
21+
*/
22+
public interface Appender extends BaseAppender {
23+
}

‎log4j-docgen/src/test/it/example/BaseAppender.java

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to you under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package example;
18+
19+
/**
20+
* Base interface for appenders.
21+
*/
22+
public interface BaseAppender {
23+
}

‎log4j-docgen/src/test/it/example/Filter.java

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to you under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package example;
18+
19+
/**
20+
* Filters messages.
21+
*/
22+
public interface Filter {
23+
}

‎log4j-docgen/src/test/it/example/Layout.java

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to you under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package example;
18+
19+
/**
20+
* Formats messages.
21+
*/
22+
public interface Layout {
23+
}

‎log4j-docgen/src/test/it/example/MyAppender.java

+189
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to you under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package example;
18+
19+
import java.util.List;
20+
import java.util.Set;
21+
import javax.lang.model.element.TypeElement;
22+
import org.apache.logging.log4j.plugins.Namespace;
23+
import org.apache.logging.log4j.plugins.Plugin;
24+
import org.apache.logging.log4j.plugins.PluginBuilderAttribute;
25+
import org.apache.logging.log4j.plugins.PluginElement;
26+
import org.apache.logging.log4j.plugins.PluginFactory;
27+
28+
/**
29+
* Example plugin
30+
* <p>
31+
* This is an example plugin. It has the following characteristics:
32+
* </p>
33+
* <ol>
34+
* <li>Plugin name: {@code MyPlugin},</li>
35+
* <li>Namespace: default (i.e. {@code Core}).</li>
36+
* </ol>
37+
* <p>
38+
* It also implements:
39+
* </p>
40+
* <ul>
41+
* <li>{@link Appender},</li>
42+
* <li>{@link BaseAppender}</li>
43+
* </ul>
44+
*/
45+
@Plugin
46+
@Namespace("namespace")
47+
public final class MyAppender extends AbstractAppender implements Appender {
48+
49+
/**
50+
* Parent builder with some private fields that are not returned by
51+
* {@link javax.lang.model.util.Elements#getAllMembers(TypeElement)}.
52+
*/
53+
public static class ParentBuilder {
54+
55+
/**
56+
* A {@code char} attribute.
57+
*/
58+
@PluginBuilderAttribute
59+
private char charAtt = 'L';
60+
61+
/**
62+
* An {@code int} attribute.
63+
*/
64+
@PluginBuilderAttribute
65+
private int intAtt = 4242;
66+
67+
/**
68+
* An element with multiplicity 1.
69+
*/
70+
@PluginElement
71+
private Layout layout;
72+
}
73+
74+
public static final class Builder extends ParentBuilder
75+
implements org.apache.logging.log4j.plugins.util.Builder<MyAppender> {
76+
77+
/**
78+
* A {@code short} attribute annotated on type.
79+
*/
80+
private @PluginBuilderAttribute short shortAtt = 42;
81+
82+
/**
83+
* A {@code long} attribute annotated on type.
84+
*/
85+
private @PluginBuilderAttribute long longAtt = 424242L;
86+
87+
/**
88+
* A {@code String} attribute.
89+
*/
90+
@PluginBuilderAttribute
91+
private String stringAtt;
92+
93+
/**
94+
* An attribute whose name differs from the field name.
95+
*/
96+
@PluginBuilderAttribute("anotherName")
97+
private String origName;
98+
99+
/**
100+
* An attribute that is an enumeration annotated on type.
101+
*/
102+
private @PluginBuilderAttribute MyEnum enumAtt;
103+
104+
/**
105+
* An attribute of type {@code float}.
106+
*/
107+
private @PluginBuilderAttribute float floatAtt;
108+
109+
/**
110+
* An attribute of type {@code double}.
111+
*/
112+
private @PluginBuilderAttribute double aDouble;
113+
114+
private Object notAnAttribute;
115+
116+
/**
117+
* A collection element.
118+
*/
119+
@PluginElement
120+
private List<Appender2> appenderList;
121+
122+
/**
123+
* A set of layouts
124+
*/
125+
@PluginElement
126+
private LayoutSet layoutSet;
127+
128+
/**
129+
* A {@code boolean} attribute with annotated type.
130+
*/
131+
public Builder setBooleanAtt(final @PluginBuilderAttribute boolean booleanAtt) {
132+
return this;
133+
}
134+
135+
/**
136+
* A {@code byte} attribute with annotated parameter.
137+
*/
138+
public Builder setByteAtt(@PluginBuilderAttribute final byte byteAtt) {
139+
return this;
140+
}
141+
142+
/**
143+
* An element with multiplicity n with annotated setter.
144+
*/
145+
@PluginElement
146+
public Builder setFilters(final Filter[] filters) {
147+
return this;
148+
}
149+
150+
/**
151+
* An element that is not an interface with annotated parameter.
152+
*/
153+
public Builder setAbstractElement(@PluginElement final AbstractAppender abstractAppender) {
154+
return this;
155+
}
156+
157+
/**
158+
* An element with an annotated type.
159+
*/
160+
public Builder setNestedAppender(final @PluginElement Appender nestedAppender) {
161+
return this;
162+
}
163+
164+
/**
165+
* A setter with a varargs type.
166+
*/
167+
public Builder setVarargs(@PluginElement final Layout3... layouts) {
168+
return this;
169+
}
170+
171+
@Override
172+
public MyAppender build() {
173+
return null;
174+
}
175+
}
176+
177+
@PluginFactory
178+
public static Builder newBuilder() {
179+
return new Builder();
180+
}
181+
182+
public static interface Appender2 {}
183+
184+
public static interface Layout2 {}
185+
186+
public static interface Layout3 {}
187+
188+
public abstract static class LayoutSet implements Set<Layout2> {}
189+
}

‎log4j-docgen/src/test/it/example/MyEnum.java

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to you under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package example;
18+
19+
/**
20+
* A very important enum.
21+
*/
22+
public enum MyEnum {
23+
/**
24+
* Makes things go boom!
25+
*/
26+
A,
27+
/**
28+
* A second choice.
29+
*/
30+
B,
31+
/**
32+
* Value C.
33+
*/
34+
C,
35+
/**
36+
* Value D.
37+
*/
38+
D;
39+
}

0 commit comments

Comments
 (0)