[logging-log4j2] 02/04: Add more DI API docs

[ma...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mattsicker pushed a commit to branch mean-bean-machine
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git

commit 79561f875b74f60ae23743fcef1e91d2089fe006
Author: Matt Sicker <bo...@gmail.com>
AuthorDate: Sun Jun 13 11:57:54 2021 -0500

    Add more DI API docs
---
 .../org/apache/logging/log4j/plugins/di/Inject.java | 21 +++++++++++++++++++++
 .../logging/log4j/plugins/di/PostConstruct.java     |  6 ++++++
 .../apache/logging/log4j/plugins/di/PreDestroy.java |  4 ++++
 3 files changed, 31 insertions(+)

diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Inject.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Inject.java
index b25e7f6..dbe62d8 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Inject.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Inject.java
@@ -23,6 +23,27 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Marks a constructor, field, or method for dependency injection. Constructors are injected first, followed by fields,
+ * then methods. Superclasses are injected before subclasses. Note that zero-arg methods with this annotation are
+ * considered initialization methods which are also invoked during dependency injection.
+ *
+ * <h2>Constructors</h2>
+ * A class can have at most one constructor annotated with {@code @Inject}. This constructor can have zero or more
+ * dependencies as arguments. If a class has no constructors annotated with {@code @Inject}, then its default
+ * zero args constructor is used if available.
+ *
+ * <h2>Fields</h2>
+ * Both static and non-static fields may be annotated with {@code @Inject}. These fields must not be final.
+ *
+ * <h2>Methods</h2>
+ * Non-abstract methods (both static and non-static) may be annotated with {@code @Inject}. These methods must not
+ * declare any type parameters of their own, take zero or more dependencies as arguments, and may return a value which
+ * is ignored (e.g., for builder method chaining).
+ *
+ * @see QualifierType
+ * @see Provider
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.FIELD})
 @Documented
diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PostConstruct.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PostConstruct.java
index d70bbf3..56059a7 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PostConstruct.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PostConstruct.java
@@ -23,6 +23,12 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Marks a method as a post construct callback. These methods are invoked after dependency injection is complete but
+ * before the injection target instance is returned. Post construct callbacks are invoked superclass-first.
+ *
+ * @see PreDestroy
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 @Documented
diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PreDestroy.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PreDestroy.java
index acf9f65..530f22a 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PreDestroy.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PreDestroy.java
@@ -23,6 +23,10 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Marks a method as a pre destroy callback. These methods are invoked before an instance is destroyed. These are
+ * invoked subclass-first.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 @Documented