azure-core JavaDocs and code snippet clean-up

sdk/core/azure-core/src/main/java/com/azure/core/cryptography/package-info.java

@@ -2,6 +2,6 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing core cryptography interfaces
+ * Package containing core cryptography interfaces.
  */
 package com.azure.core.cryptography;

sdk/core/azure-core/src/main/java/com/azure/core/exception/package-info.java

@@ -2,6 +2,6 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing core exception classes
+ * Package containing core exception classes.
  */
 package com.azure.core.exception;

sdk/core/azure-core/src/main/java/com/azure/core/http/package-info.java

@@ -2,6 +2,6 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing the HTTP abstractions between the AnnotationParser, RestProxy and HTTP client.
+ * Package containing HTTP abstractions between the AnnotationParser, RestProxy, and HTTP client.
  */
 package com.azure.core.http;

sdk/core/azure-core/src/main/java/com/azure/core/http/policy/package-info.java

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing HttpPipelinePolicy interface and it's implementations.
+ * Package containing HttpPipelinePolicy interface and its implementations.
  */
 package com.azure.core.http.policy;
 

sdk/core/azure-core/src/main/java/com/azure/core/util/logging/ClientLogger.java

@@ -11,15 +11,15 @@
 import java.util.Objects;
 
 /**
- * This is a fluent logger helper class that wraps a plug-able {@link Logger}.
+ * This is a fluent logger helper class that wraps a pluggable {@link Logger}.
  *
- * <p>This logger logs formattable messages that use {@code {}} as the placeholder. When a throwable is the last
- * argument of the format varargs and the logger is enabled for {@link ClientLogger#verbose(String, Object...) verbose}
- * logging the stack trace for the throwable will be included in the log message.</p>
+ * <p>This logger logs formattable messages that use {@code {}} as the placeholder. When a {@link Throwable throwable}
+ * is the last argument of the format varargs and the logger is enabled for
+ * {@link ClientLogger#verbose(String, Object...) verbose}, the stack trace for the throwable is logged.</p>
  *
  * <p>A minimum logging level threshold is determined by the
- * {@link Configuration#PROPERTY_AZURE_LOG_LEVEL AZURE_LOG_LEVEL} environment configuration, by default logging is
- * disabled.</p>
+ * {@link Configuration#PROPERTY_AZURE_LOG_LEVEL AZURE_LOG_LEVEL} environment configuration. By default logging is
+ * <b>disabled</b>.</p>
  *
  * <p><strong>Log level hierarchy</strong></p>
  * <ol>
@@ -78,60 +78,64 @@ public ClientLogger(String className) {
     }
 
     /**
-     * Logs a formattable message that uses {@code {}} as the placeholder at {@code verbose} log level
+     * Logs a formattable message that uses {@code {}} as the placeholder at {@code verbose} log level.
      *
-     * <p><strong>Code Samples</strong></p>
+     * <p><strong>Code samples</strong></p>
      * <p>
-     * Logging a message at verbose log level
-     * {@codesnippet com.azure.core.implementation.util.clientlogger.verbose}
+     * Logging a message at verbose log level.
+     * {@codesnippet com.azure.core.util.logging.clientlogger.verbose}
      *
-     * @param format The formattable message to log
-     * @param args Arguments for the message, if an exception is being logged last argument is the throwable.
+     * @param format The formattable message to log.
+     * @param args Arguments for the message. If an exception is being logged, the last argument should be the
+     *     {@link Throwable}.
      */
     public void verbose(String format, Object... args) {
         log(VERBOSE_LEVEL, format, args);
     }
 
     /**
-     * Logs a formattable message that uses {@code {}} as the placeholder at {@code informational} log level
+     * Logs a formattable message that uses {@code {}} as the placeholder at {@code informational} log level.
      *
-     * <p><strong>Code Samples</strong></p>
+     * <p><strong>Code samples</strong></p>
      * <p>
-     * Logging a message at informational log level
-     * {@codesnippet com.azure.core.implementation.util.clientlogger.info}
+     * Logging a message at informational log level.
+     * {@codesnippet com.azure.core.util.logging.clientlogger.info}
      *
      * @param format The formattable message to log
-     * @param args Arguments for the message, if an exception is being logged last argument is the throwable.
+     * @param args Arguments for the message. If an exception is being logged, the last argument should be the
+     *     {@link Throwable}.
      */
     public void info(String format, Object... args) {
         log(INFORMATIONAL_LEVEL, format, args);
     }
 
     /**
-     * Logs a formattable message that uses {@code {}} as the placeholder at {@code warning} log level
+     * Logs a formattable message that uses {@code {}} as the placeholder at {@code warning} log level.
      *
-     * <p><strong>Code Samples</strong></p>
+     * <p><strong>Code samples</strong></p>
      * <p>
-     * Logging a message at warning log level
-     * {@codesnippet com.azure.core.implementation.util.clientlogger.warning}
+     * Logging a message at warning log level.
+     * {@codesnippet com.azure.core.util.logging.clientlogger.warning}
      *
-     * @param format The formattable message to log
-     * @param args Arguments for the message, if an exception is being logged last argument is the throwable.
+     * @param format The formattable message to log.
+     * @param args Arguments for the message. If an exception is being logged, the last argument should be the
+     *     {@link Throwable}.
      */
     public void warning(String format, Object... args) {
         log(WARNING_LEVEL, format, args);
     }
 
     /**
-     * Logs a formattable message that uses {@code {}} as the placeholder at {@code error} log level
+     * Logs a formattable message that uses {@code {}} as the placeholder at {@code error} log level.
      *
-     * <p><strong>Code Samples</strong></p>
+     * <p><strong>Code samples</strong></p>
      * <p>
-     * Logging an error with stack trace
-     * {@codesnippet com.azure.core.implementation.util.clientlogger.error}
+     * Logging an error with stack trace.
+     * {@codesnippet com.azure.core.util.logging.clientlogger.error}
      *
-     * @param format The formattable message to log
-     * @param args Arguments for the message, if an exception is being logged last argument is the throwable.
+     * @param format The formattable message to log.
+     * @param args Arguments for the message. If an exception is being logged, the last argument should be the
+     *     {@link Throwable}.
      */
     public void error(String format, Object... args) {
         log(ERROR_LEVEL, format, args);
@@ -151,21 +155,21 @@ private void log(int logLevel, String format, Object... args) {
     }
 
     /**
-     * Attempts to log the {@link RuntimeException} at the warning level and returns it to be thrown.
+     * Logs the {@link RuntimeException} at the warning level and returns it to be thrown.
      *
      * @param runtimeException RuntimeException to be logged and returned.
-     * @return the passed {@code RuntimeException}
+     * @return The passed {@code RuntimeException}.
      * @throws NullPointerException If {@code runtimeException} is {@code null}.
      */
     public RuntimeException logExceptionAsWarning(RuntimeException runtimeException) {
         return logException(runtimeException, WARNING_LEVEL);
     }
 
     /**
-     * Attempts to log the {@link RuntimeException} at the error level and returns it to be thrown.
+     * Logs the {@link RuntimeException} at the error level and returns it to be thrown.
      *
      * @param runtimeException RuntimeException to be logged and returned.
-     * @return the passed {@code RuntimeException}
+     * @return The passed {@code RuntimeException}.
      * @throws NullPointerException If {@code runtimeException} is {@code null}.
      */
     public RuntimeException logExceptionAsError(RuntimeException runtimeException) {

sdk/core/azure-core/src/main/java/com/azure/core/util/logging/package-info.java

@@ -2,6 +2,6 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing implementation-specific APIs that should not be used by end-users.
+ * Package containing logging APIs.
  */
 package com.azure.core.util.logging;

sdk/core/azure-core/src/main/java/com/azure/core/util/package-info.java

@@ -2,6 +2,6 @@
 // Licensed under the MIT License.
 
 /**
- * Package containing core utility classes
+ * Package containing core utility classes.
  */
 package com.azure.core.util;