Merge pull request #57 from microsoftgraph/javadoc-cleanup

Javadoc cleanup

Author: Caitlin Bales (MSFT)

src/main/java/com/microsoft/graph/authentication/IAuthenticationProvider.java

@@ -25,13 +25,14 @@
 import com.microsoft.graph.http.IHttpRequest;
 
 /**
- * Provides authentication for a requests before it is sent by an HTTP provider.
+ * Provides authentication for a requests before it is sent by an HTTP provider
  */
 public interface IAuthenticationProvider {
 
     /**
-     * Authenticates the request.
-     * @param request The request to authenticate.
+     * Authenticates the request
+     * 
+     * @param request the request to authenticate
      */
     void authenticateRequest(final IHttpRequest request);
 }

src/main/java/com/microsoft/graph/concurrency/ChunkedUploadProvider.java

@@ -37,9 +37,9 @@
 import java.util.List;
 
 /**
- * ChunkedUpload service provider.
+ * ChunkedUpload service provider
  *
- * @param <UploadType> The upload item type.
+ * @param <UploadType> the upload item type
  */
 public class ChunkedUploadProvider<UploadType> {
 
@@ -49,7 +49,7 @@ public class ChunkedUploadProvider<UploadType> {
     private static final int DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024;
 
     /**
-     * The required chunk size increment by OneDrive service, which is 320 KiB.
+     * The required chunk size increment by OneDrive service, which is 320 KiB
      */
     private static final int REQUIRED_CHUNK_SIZE_INCREMENT = 320 * 1024;
 
@@ -60,48 +60,48 @@ public class ChunkedUploadProvider<UploadType> {
     private static final int MAXIMUM_CHUNK_SIZE = 60 * 1024 * 1024;
 
     /**
-     * The default retry times for a simple chunk upload if failure happened.
+     * The default retry times for a simple chunk upload if failure happened
      */
     private static final int MAXIMUM_RETRY_TIMES = 3;
 
     /**
-     * The client.
+     * The client
      */
     private final IGraphServiceClient client;
 
     /**
-     * The input stream.
+     * The input stream
      */
     private final InputStream inputStream;
 
     /**
-     * The upload session URL.
+     * The upload session URL
      */
     private final String uploadUrl;
 
     /**
-     * The stream size.
+     * The stream size
      */
     private final int streamSize;
 
     /**
-     * The upload response handler.
+     * The upload response handler
      */
     private final ChunkedUploadResponseHandler<UploadType> responseHandler;
 
     /**
-     * The counter for how many bytes have been read from input stream.
+     * The counter for how many bytes have been read from input stream
      */
     private int readSoFar;
 
     /**
-     * Create the ChunkedUploadProvider
+     * Creates the ChunkedUploadProvider
      *
-     * @param uploadSession   The initial upload session.
-     * @param client          The OneDrive client.
-     * @param inputStream     The input stream.
-     * @param streamSize      The stream size.
-     * @param uploadTypeClass The upload type class.
+     * @param uploadSession   the initial upload session
+     * @param client          the Graph client
+     * @param inputStream     the input stream
+     * @param streamSize      the stream size
+     * @param uploadTypeClass the upload type class
      */
     public ChunkedUploadProvider(final UploadSession uploadSession,
                                  final IGraphServiceClient client,
@@ -133,13 +133,13 @@ public ChunkedUploadProvider(final UploadSession uploadSession,
     }
 
     /**
-     * Upload content to remote upload session based on the input stream.
+     * Uploads content to remote upload session based on the input stream
      *
-     * @param options  The upload options.
-     * @param callback The progress callback invoked during uploading.
-     * @param configs  The optional configurations for the upload options, [0] should be the customized chunk
-     *                 size and the [1] should be the maxRetry for upload retry.
-     * @throws IOException The IO exception happened during upload.
+     * @param options  the upload options
+     * @param callback the progress callback invoked during uploading
+     * @param configs  the optional configurations for the upload options. [0] should be the customized chunk
+     *                 size and [1] should be the maxRetry for upload retry.
+     * @throws IOException the IO exception that occurred during upload
      */
     public void upload(final List<Option> options,
                        final IProgressCallback<UploadType> callback,

src/main/java/com/microsoft/graph/concurrency/ChunkedUploadResponseHandler.java

@@ -37,45 +37,45 @@
 import java.io.InputStream;
 
 /**
- * The class handles the stateful response from OneDrive upload session.
+ * Handles the stateful response from the OneDrive upload session
  *
- * @param <UploadType> The expected uploaded item.
+ * @param <UploadType> the expected uploaded item
  */
 public class ChunkedUploadResponseHandler<UploadType>
         implements IStatefulResponseHandler<ChunkedUploadResult, UploadType> {
     /**
-     * The expected deserialize type for upload type.
+     * The expected deserialized upload type
      */
     private final Class<UploadType> deserializeTypeClass;
 
     /**
-     * Create a chunked upload response handler.
+     * Creates a chunked upload response handler
      *
-     * @param uploadType The expected upload item type.
+     * @param uploadType the expected upload item type
      */
     public ChunkedUploadResponseHandler(final Class<UploadType> uploadType) {
         this.deserializeTypeClass = uploadType;
     }
 
     /**
-     * Do nothing before get response.
+     * Do nothing before getting the response
      *
-     * @param connection The connection.
+     * @param connection the connection
      */
     @Override
     public void configConnection(final IConnection connection) {
         return;
     }
 
     /**
-     * Generate the chunked upload response result.
+     * Generate the chunked upload response result
      *
-     * @param request    The HTTP request.
-     * @param connection The HTTP connection.
-     * @param serializer The serializer.
-     * @param logger     The system logger.
-     * @return The chunked upload result which could be upload session/uploaded item or error.
-     * @throws Exception An exception occurs if the request was unable to complete for any reason.
+     * @param request    the HTTP request
+     * @param connection the HTTP connection
+     * @param serializer the serializer
+     * @param logger     the system logger
+     * @return the chunked upload result, which could be either an uploaded item or error
+     * @throws Exception an exception occurs if the request was unable to complete for any reason
      */
     @Override
     public ChunkedUploadResult<UploadType> generateResult(

src/main/java/com/microsoft/graph/concurrency/DefaultExecutors.java

@@ -29,28 +29,29 @@
 import java.util.concurrent.ThreadPoolExecutor;
 
 /**
- * The default executors implementation for the SDK.
+ * The default executors implementation for the SDK
  */
 public class DefaultExecutors implements IExecutors {
 
     /**
-     * The executor for handling background actions.
+     * The executor for handling background actions
      */
     private final ThreadPoolExecutor backgroundExecutor;
 
     /**
-     * The executor for handling foreground actions.
+     * The executor for handling foreground actions
      */
     private final SynchronousExecutor foregroundExecutor;
 
     /**
-     * The logger.
+     * The logger
      */
     private final ILogger logger;
 
     /**
-     * Creates a new instance of the DefaultExecutors.
-     * @param logger The logger.
+     * Creates a new instance of the DefaultExecutors
+     * 
+     * @param logger the logger
      */
     public DefaultExecutors(final ILogger logger) {
     	this.logger = logger;
@@ -59,8 +60,9 @@ public DefaultExecutors(final ILogger logger) {
     }
 
     /**
-     * Runs the given Runnable on the background thread.
-     * @param runnable The Runnable to execute.
+     * Runs the given Runnable on the background thread
+     * 
+     * @param runnable the Runnable to execute
      */
     @Override
     public void performOnBackground(final Runnable runnable) {
@@ -70,10 +72,11 @@ public void performOnBackground(final Runnable runnable) {
     }
 
     /**
-     * Performs the given callback with the result object.
-     * @param result The result value.
-     * @param callback The callback to call on the foreground with this result.
-     * @param <Result> The result type.
+     * Performs the given callback with the result object
+     * 
+     * @param result   the result value
+     * @param callback the callback to call on the foreground with this result
+     * @param <Result> the result type
      */
     @Override
     public <Result> void performOnForeground(final Result result,
@@ -91,11 +94,12 @@ public void run() {
     }
 
     /**
-     * Performs the given callback with the result object.
-     * @param progress The progress value.
-     * @param progressMax The progress value.
-     * @param callback The callback to call on the foreground with this result.
-     * @param <Result> The result type.
+     * Performs the given callback with the result object
+     * 
+     * @param progress    the progress value
+     * @param progressMax the progress value
+     * @param callback    the callback to call on the foreground with this result
+     * @param <Result>    the result type
      */
     public <Result> void performOnForeground(final int progress,
                                              final int progressMax,
@@ -114,10 +118,11 @@ public void run() {
         });
     }
     /**
-     * Performs the given callback with the exception object.
-     * @param exception The exception value.
-     * @param callback The callback to call on the foreground with this exception.
-     * @param <Result> The result type.
+     * Performs the given callback with the exception object
+     * 
+     * @param exception the exception value
+     * @param callback  the callback to call on the foreground with this exception
+     * @param <Result>  the result type
      */
     @Override
     public <Result> void performOnForeground(final ClientException exception,

src/main/java/com/microsoft/graph/concurrency/ICallback.java

@@ -25,19 +25,22 @@
 import com.microsoft.graph.core.ClientException;
 
 /**
- * A callback that describes how to deal with success and failure.
- * @param <Result> The result type of the successful action.
+ * A callback that describes how to deal with success and failure
+ * 
+ * @param <Result> the result type of the successful action
  */
 public interface ICallback<Result> {
     /**
-     * How successful results are handled.
-     * @param result The result.
+     * How successful results are handled
+     * 
+     * @param result the result
      */
     void success(final Result result);
 
     /**
-     * How failures are handled.
-     * @param ex The exception.
+     * How failures are handled
+     * 
+     * @param ex the exception
      */
     void failure(final ClientException ex);
 }

src/main/java/com/microsoft/graph/concurrency/IExecutors.java

@@ -25,41 +25,45 @@
 import com.microsoft.graph.core.ClientException;
 
 /**
- * A way to manage scheduled actions that are run in the foreground or background threading environments.
+ * A way to manage scheduled actions that are run in the foreground or background threading environments
  */
 public interface IExecutors {
 
     /**
-     * Runs the given Runnable on the background thread.
-     * @param runnable The Runnable to execute.
+     * Runs the given Runnable on the background thread
+     * 
+     * @param runnable the Runnable to execute
      */
     void performOnBackground(final Runnable runnable);
 
     /**
-     * Performs the given callback with the result object.
-     * @param result The result value.
-     * @param callback The callback to call on the foreground with this result.
-     * @param <Result> The result type.
+     * Performs the given callback with the result object
+     *
+     * @param result   the result value
+     * @param callback the callback to call on the foreground with this result
+     * @param <Result> the result type
      */
     <Result> void performOnForeground(final Result result,
                                       final ICallback<Result> callback);
 
     /**
-     * Performs the given callback with the result object.
-     * @param progress The progress value.
-     * @param progressMax The progress value.
-     * @param callback The callback to call on the foreground with this result.
-     * @param <Result> The result type.
+     * Performs the given callback with the result object
+     * 
+     * @param progress    the progress value
+     * @param progressMax the max progress value
+     * @param callback    the callback to call on the foreground with this result
+     * @param <Result>    the result type
      */
     <Result> void performOnForeground(final int progress,
                                       final int progressMax,
                                       final IProgressCallback<Result> callback);
 
     /**
-     * Performs the given callback with the exception object.
-     * @param exception The exception value.
-     * @param callback The callback to call on the foreground with this exception.
-     * @param <Result> The result type.
+     * Performs the given callback with the exception object
+     * 
+     * @param exception the exception value
+     * @param callback the callback to call on the foreground with this exception
+     * @param <Result> the result type
      */
     <Result> void performOnForeground(final ClientException exception,
                                       final ICallback<Result> callback);

src/main/java/com/microsoft/graph/concurrency/IProgressCallback.java

@@ -23,15 +23,17 @@
 package com.microsoft.graph.concurrency;
 
 /**
- * A callback that describes how to deal with success, failure, and progress.
- * @param <Result> The result type of the successful action.
+ * A callback that describes how to deal with success, failure, and progress
+ * 
+ * @param <Result> the result type of the successful action
  */
 public interface IProgressCallback<Result> extends ICallback<Result> {
 
     /**
-     * How progress updates are handled for this callback.
-     * @param current The current amount of progress.
-     * @param max The max amount of progress.
+     * How progress updates are handled for this callback
+     * 
+     * @param current the current amount of progress
+     * @param max     the max amount of progress
      */
     void progress(final long current, final long max);
 }