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.

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,141 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example;
+
+import org.apache.logging.log4j.plugins.Namespace;
+import org.apache.logging.log4j.plugins.Plugin;
+import org.apache.logging.log4j.plugins.PluginBuilderAttribute;
+import org.apache.logging.log4j.plugins.PluginElement;
+import org.apache.logging.log4j.plugins.PluginFactory;
+
+/**
+ * Example plugin
+ * <p>
+ * This is an example plugin. It has the following characteristics:
+ * </p>
+ * <ol>
+ * <li>Plugin name: {@code MyPlugin},</li>
+ * <li>Namespace: default (i.e. {@code Core}).</li>
+ * </ol>
+ * <p>
+ * It also implements:
+ * </p>
+ * <ul>
+ * <li>{@link Appender},</li>
+ * <li>{@link BaseAppender}</li>
+ * </ul>
+ */
+@Plugin
+@Namespace("namespace")
+public final class MyAppender extends AbstractAppender implements Appender {
+
+ public static final class Builder implements org.apache.logging.log4j.plugins.util.Builder<MyAppender> {
+
+ /**
+ * A {@code char} attribute.
+ */
+ @PluginBuilderAttribute
+ private char charAtt = 'L';
+
+ /**
+ * A {@code short} attribute annotated on type.
+ */
+ private @PluginBuilderAttribute short shortAtt = 42;
+
+ /**
+ * An {@code int} attribute.
+ */
+ @PluginBuilderAttribute
+ private int intAtt = 4242;
+
+ /**
+ * A {@code long} attribute annotated on type.
+ */
+ private @PluginBuilderAttribute long longAtt = 424242L;
+
+ /**
+ * A {@code String} attribute.
+ */
+ @PluginBuilderAttribute
+ private String stringAtt;
+
+ /**
+ * An attribute whose name differs from the field name.
+ */
+ @PluginBuilderAttribute("anotherName")
+ private String origName;
+
+ /**
+ * An attribute that is an enumeration annotated on type.
+ */
+ private @PluginBuilderAttribute MyEnum enumAtt;
+
+ /**
+ * An attribute of type {@code float}.
+ */
+ private @PluginBuilderAttribute float floatAtt;
+
+ /**
+ * An attribute of type {@code double}.
+ */
+ private @PluginBuilderAttribute double aDouble;
+
+ /**
+ * An element with multiplicity 1.
+ */
+ @PluginElement
+ private Layout layout;
+
+ private Object notAnAttribute;
+
+ /**
+ * A {@code boolean} attribute with annotated type.
+ */
+ public void setBooleanAtt(final @PluginBuilderAttribute boolean booleanAtt) {}
+
+ /**
+ * A {@code byte} attribute with annotated parameter.
+ */
+ public void setByteAtt(@PluginBuilderAttribute final byte byteAtt) {}
+
+ /**
+ * An element with multiplicity n with annotated setter.
+ */
+ @PluginElement
+ public void setFilters(final Filter[] filters) {}
+
+ /**
+ * An element that is not an interface with annotated parameter.
+ */
+ public void setAbstractElement(@PluginElement final AbstractAppender abstractAppender) {}
+
+ /**
+ * An element with an annotated type.
+ */
+ public void setNestedAppender(final @PluginElement Appender nestedAppender) {}
+
+ @Override
+ public MyAppender build() {
+ return null;
+ }
+ }
+
+ @PluginFactory
+ public static Builder newBuilder() {
+ return new Builder();
+ }
+}

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

@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example;
+
+/**
+ * A very important enum.
+ */
+public enum MyEnum {
+ /**
+ * Makes things go boom!
+ */
+ A,
+ /**
+ * A second choice.
+ */
+ B,
+ /**
+ * Value C.
+ */
+ C,
+ /**
+ * Value D.
+ */
+ D;
+}

log4j-docgen/src/test/it/example/MyOldLayout.java

@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example;
+
+import org.apache.logging.log4j.plugins.Factory;
+import org.apache.logging.log4j.plugins.Plugin;
+import org.apache.logging.log4j.plugins.PluginAttribute;
+import org.apache.logging.log4j.plugins.PluginElement;
+
+/**
+ * Example plugin without a builder.
+ */
+@Plugin
+public final class MyOldLayout implements Layout {
+
+ /**
+ * @param boolAttr A {@code boolean} attribute.
+ * @param byteAttr A {@code byte} attribute.
+ * @param charAttr A {@code char} attribute.
+ * @param doubleAttr A {@code double} attribute.
+ * @param floatAttr A {@code float} attribute.
+ * @param intAttr An {@code int} attribute.
+ * @param longAttr A {@code long} attribute.
+ * @param shortAttr A {@code short} attribute.
+ * @param stringAttr A {@link String} attribute.
+ * @param origName An attribute with overwritten name.
+ * @param enumAttr An {@code enum} attribute.
+ * @param nestedLayout An element with multiplicity {@code 1}.
+ * @param filters An element with multiplicity {@code n}.
+ */
+ @Factory
+ public static MyOldLayout newLayout(
+ final @PluginAttribute(defaultBoolean = false) boolean boolAttr,
+ final @PluginAttribute(defaultByte = 'L') byte byteAttr,
+ final @PluginAttribute(defaultChar = 'L') char charAttr,
+ final @PluginAttribute(defaultDouble = 42.0) double doubleAttr,
+ final @PluginAttribute(defaultFloat = 42.0f) float floatAttr,
+ final @PluginAttribute(defaultInt = 424242) int intAttr,
+ final @PluginAttribute(defaultLong = 42424242L) long longAttr,
+ final @PluginAttribute(defaultShort = 4242) short shortAttr,
+ final @PluginAttribute String stringAttr,
+ final @PluginAttribute("otherName") String origName,
+ final @PluginAttribute MyEnum enumAttr,
+ final @PluginElement Layout nestedLayout,
+ final @PluginElement Filter[] filters) {
+ return null;
+ }
+}