docs: fix example in javadoc, update version number and usage (#92)

* Updated version number to latest release. Improved documentation: - Synced Javadoc and `README.md`, correcting error about filter in Javadoc - Made example in Javadoc more easy to read and copy * Changed to use the original example enhancers from README.md.
googleapis · Jun 17, 2020 · 4ad9d23 · 4ad9d23
1 parent 3a57207
commit 4ad9d23
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 31 deletions.
diff --git a/README.md b/README.md
@@ -73,18 +73,28 @@ See [Logback filters](https://logback.qos.ch/manual/filters.html#thresholdFilter
 ```xml
 <configuration>
   <appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender">
-    <!-- Optional : filter logs at or above a level -->
+    <!-- Optional: filter logs at and above this level --> 
     <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
-      <level>INFO</level>
+        <level>INFO</level>
     </filter>
-    <log>application.log</log> <!-- Optional : default java.log -->
-    <!-- Optional : will use the default credentials of the environment if this property is not set -->
-    <credentialsFile>/path/to/credentials.json</credentialsFile>
-    <enhancer>com.example.enhancers.TestLoggingEnhancer</enhancer> <!-- Optional -->
-    <enhancer>com.example.enhancers.AnotherEnhancer</enhancer> <!-- Optional -->
-    <flushLevel>WARN</flushLevel> <!-- Optional : default ERROR -->
+
+    <!-- Optional: defaults to "java.log" -->
+    <log>application.log</log>
+
+    <!-- Optional: defaults to "ERROR" -->
+    <flushLevel>WARNING</flushLevel>
+
+    <!-- Optional: auto detects on App Engine Flex, Standard, GCE and GKE, defaults to "global". See supported resource types  -->
+    <resourceType></resourceType>
+
+    <!-- Optional: defaults to the default credentials of the environment -->
+    <credentialsFile>/path/to/credentials/file</credentialsFile>
+
+    <!-- Optional: add custom labels to log entries using LoggingEnhancer classes -->
+    <enhancer>com.example.enhancers.TestLoggingEnhancer</enhancer>
+    <enhancer>com.example.enhancers.AnotherEnhancer</enhancer>
   </appender>
-
+   
   <root level="info">
     <appender-ref ref="CLOUD" />
   </root>

diff --git a/src/main/java/com/google/cloud/logging/logback/LoggingAppender.java b/src/main/java/com/google/cloud/logging/logback/LoggingAppender.java
@@ -46,28 +46,35 @@
 import java.util.Set;
 
 /**
- * <a href="https://logback.qos.ch/">Logback</a> appender for StackDriver Cloud Logging.
+ * <a href="https://logback.qos.ch/">Logback</a> appender for Google Cloud Logging.
  *
- * <p>Appender configuration in logback.xml:
+ * <p>Appender configuration in <code>logback.xml</code>:
  *
- * <ul>
- *   <li>&lt;appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender"&gt;
- *   <li>&lt;log&gt;application.log&lt;/log&gt; (Optional, defaults to "java.log" : Stackdriver log
- *       name)
- *   <li>&lt;level&gt;ERROR&lt;/level&gt; (Optional, defaults to "INFO" : logs at or above this
- *       level)
- *   <li>&lt;flushLevel&gt;WARNING&lt;/flushLevel&gt; (Optional, defaults to "ERROR")
- *   <li>&lt;resourceType&gt;&lt;/resourceType&gt; (Optional, auto detects on App Engine Flex,
- *       Standard, GCE and GKE, defaults to "global". See <a
- *       href="https://cloud.google.com/logging/docs/api/v2/resource-list">supported resource
- *       types</a>
- *   <li>&lt;credentialsFile&gt;/path/to/credentials/file&lt;/credentialsFile&gt; (Optional,
- *       defaults to the default credentials of the environment)
- *   <li>(Optional) add custom labels to log entries using {@link LoggingEnhancer} classes.
- *   <li>&lt;enhancer&gt;com.example.enhancer1&lt;/enhancer&gt;
- *   <li>&lt;enhancer&gt;com.example.enhancer2&lt;/enhancer&gt;
- *   <li>&lt;/appender&gt;
- * </ul>
+ * <pre>
+ *    &lt;appender name="CLOUD" class="com.google.cloud.logging.logback.LoggingAppender"&gt;
+ *         &lt;!-- Optional: filter logs at and above this level --&gt;
+ *         &lt;filter class="ch.qos.logback.classic.filter.ThresholdFilter"&gt;
+ *             &lt;level&gt;INFO&lt;/level&gt;
+ *         &lt;/filter&gt;
+ *
+ *         &lt;!-- Optional: defaults to "java.log" --&gt;
+ *         &lt;log&gt;application.log&lt;/log&gt;
+ *
+ *         &lt;!-- Optional: defaults to "ERROR" --&gt;
+ *         &lt;flushLevel&gt;WARNING&lt;/flushLevel&gt;
+ *
+ *         &lt;!-- Optional: auto detects on App Engine Flex, Standard, GCE and GKE, defaults to "global". See <a
+ *         href="https://cloud.google.com/logging/docs/api/v2/resource-list">supported resource types</a> --&gt;
+ *         &lt;resourceType&gt;&lt;/resourceType&gt;
+ *
+ *         &lt;!-- Optional: defaults to the default credentials of the environment --&gt;
+ *         &lt;credentialsFile&gt;/path/to/credentials/file&lt;/credentialsFile&gt;
+ *
+ *         &lt;!-- Optional: add custom labels to log entries using {@link LoggingEnhancer} classes --&gt;
+ *         &lt;enhancer&gt;com.example.enhancers.TestLoggingEnhancer&lt/enhancer&gt;
+ *         &lt;enhancer&gt;com.example.enhancers.AnotherEnhancer&lt/enhancer&gt;
+ *     &lt;/appender&gt;
+ * </pre>
  */
 public class LoggingAppender extends UnsynchronizedAppenderBase<ILoggingEvent> {
 
@@ -89,8 +96,8 @@ public class LoggingAppender extends UnsynchronizedAppenderBase<ILoggingEvent> {
   private String log;
   private String resourceType;
   private String credentialsFile;
-  private Set<String> enhancerClassNames = new HashSet<>();
-  private Set<String> loggingEventEnhancerClassNames = new HashSet<>();
+  private final Set<String> enhancerClassNames = new HashSet<>();
+  private final Set<String> loggingEventEnhancerClassNames = new HashSet<>();
 
   /**
    * Batched logging requests get immediately flushed for logs at or above this level.