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;
+    }
+}