Reduces the number of JavaDoc warnings from 89 to 3 in azure-storage-…

…java (Azure#244) Reduces the number of JavaDoc warnings from 89 to 3 in azure-storage-…
g2vinay · Jan 22, 2018 · 4db7212 · 4db7212
1 parent 08b256e
commit 4db7212
Show file tree

Hide file tree

Showing 27 changed files with 47 additions and 69 deletions.
diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/AccessCondition.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/AccessCondition.java
@@ -346,9 +346,6 @@ public void applySourceConditionToRequest(final HttpURLConnection request) {
      * @param request
      *            A <code>java.net.HttpURLConnection</code> object that represents the request to which the condition is
      *            being applied.
-     * 
-     * @throws StorageException
-     *             If there is an error parsing the date value of the access condition.
      */
     public void applyAppendConditionToRequest(final HttpURLConnection request) {
         if (this.ifMaxSizeLessThanOrEqual != null) {

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/LoggingProperties.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/LoggingProperties.java
@@ -27,7 +27,7 @@ public final class LoggingProperties {
     private String version = "1.0";
 
     /**
-     * An <code>EnumSet<code> of <code>LoggingOperations</code> that represents which storage operations should be logged.
+     * An <code>EnumSet</code> of <code>LoggingOperations</code> that represents which storage operations should be logged.
      */
     private EnumSet<LoggingOperations> logOperationTypes = EnumSet.noneOf(LoggingOperations.class);
 
@@ -37,9 +37,9 @@ public final class LoggingProperties {
     private Integer retentionIntervalInDays;
 
     /**
-     * Gets an <code>EnumSet<code> of <code>{@link LoggingOperations}</code> that represents which storage operations should be logged.
+     * Gets an <code>EnumSet</code> of <code>{@link LoggingOperations}</code> that represents which storage operations should be logged.
      * 
-     * @return An <code>EnumSet<code> of <code>{@link LoggingOperations}</code>.
+     * @return An <code>EnumSet</code> of <code>{@link LoggingOperations}</code>.
      */
     public EnumSet<LoggingOperations> getLogOperationTypes() {
         return this.logOperationTypes;
@@ -67,7 +67,7 @@ public String getVersion() {
      * Sets the <code>{@link LoggingOperations}</code> for which storage operations should be logged.
      * 
      * @param logOperationTypes
-     *        An <code>EnumSet<code> of <code>{@link LoggingOperations}</code> to set.
+     *        An <code>EnumSet</code> of <code>{@link LoggingOperations}</code> to set.
      */
     public void setLogOperationTypes(final EnumSet<LoggingOperations> logOperationTypes) {
         this.logOperationTypes = logOperationTypes;

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/OperationContext.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/OperationContext.java
@@ -186,7 +186,7 @@ public OperationContext() {
     /**
      * Gets the client side trace ID.
      * 
-     * @return A <code>String</cod> which represents the client request ID.
+     * @return A <code>String</code> which represents the client request ID.
      */
     public String getClientRequestID() {
         return this.clientRequestID;

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/RetryInfo.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/RetryInfo.java
@@ -45,7 +45,7 @@ public RetryInfo() {
     }
 
     /**
-     * Initializes a new instance of the {@link "RetryInfo"} class.
+     * Initializes a new instance of the {@link RetryInfo} class.
      * 
      * @param retryContext
      *            The {@link RetryContext} object that was passed in to the retry policy.
@@ -114,7 +114,7 @@ public void setUpdatedLocationMode(LocationMode updatedLocationMode) {
     }
 
     /**
-     * Returns a string that represents the current {@link "RetryInfo"} instance.
+     * Returns a string that represents the current {@link RetryInfo} instance.
      * 
      * @return A <code>String</code> which represents the current <code>RetryInfo</code> instance.
      */

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/SharedAccessPolicyHandler.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/SharedAccessPolicyHandler.java
@@ -58,8 +58,6 @@ private SharedAccessPolicyHandler(final Class<T> cls) {
      * @return the HashMap of SharedAccessPolicies from the response
      * @throws SAXException
      * @throws ParserConfigurationException
-     * @throws ParseException
-     *             if a date is incorrectly encoded in the stream
      * @throws IOException
      */
     public static <T extends SharedAccessPolicy> HashMap<String, T> getAccessIdentifiers(final InputStream stream,

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/analytics/CloudAnalyticsClient.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/analytics/CloudAnalyticsClient.java
@@ -385,9 +385,7 @@ public Iterable<LogRecord> listLogRecords(StorageService service, Date startTime
      * @param logBlobs
      *            An {@link Iterable} of blobs to parse LogRecords from.
      * @return
-     *         An enumerable collection of objects that implement {@link LogRecords} and are retrieved lazily.
-     * @throws StorageException
-     * @throws URISyntaxException
+     *         An enumerable collection of objects that implement {@link LogRecord} and are retrieved lazily.
      */
     public static Iterable<LogRecord> parseLogBlobs(Iterable<ListBlobItem> logBlobs) {
         Utility.assertNotNull("logBlobs", logBlobs);
@@ -398,12 +396,10 @@ public static Iterable<LogRecord> parseLogBlobs(Iterable<ListBlobItem> logBlobs)
     /**
      * Returns an enumerable collection of log records, retrieved lazily.
      * 
-     * @param logBlobs
-     *            An {@link Iterable} of blobs to parse LogRecords from.
+     * @param logBlob
+     *            A single blob to parse LogRecords from.
      * @return
-     *         An enumerable collection of objects that implement {@link LogRecords} and are retrieved lazily.
-     * @throws StorageException
-     * @throws URISyntaxException
+     *         An enumerable collection of objects that implement {@link LogRecord} and are retrieved lazily.
      */
     public static Iterable<LogRecord> parseLogBlob(ListBlobItem logBlob) {
         Utility.assertNotNull("logBlob", logBlob);

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/BlobContainerProperties.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/BlobContainerProperties.java
@@ -108,10 +108,10 @@ public LeaseDuration getLeaseDuration() {
     /**
      * Gets the public access level for the container.
      * This field should only be set using the container's {@link #create(BlobContainerPublicAccessType,
-     * BlobRequestOptions, OperationContext) create} method or
+     * BlobRequestOptions, com.microsoft.azure.storage.OperationContext) create} method or
      * {@link #uploadPermissions(BlobContainerPermissions) uploadPermissions} method.
      * 
-     * @return A <code>{@link BlobContainerPublicAccessLevel}</code> that specifies the level of public access
+     * @return A <code>{@link BlobContainerPublicAccessType}</code> that specifies the level of public access
      * that is allowed on the container.
      */
     public BlobContainerPublicAccessType getPublicAccess() {
@@ -171,7 +171,7 @@ protected void setLeaseDuration(final LeaseDuration leaseDuration) {
     /**
      * Sets the public access level on the container.
      * This should only be set using the container's {@link #create(BlobContainerPublicAccessType,
-     * BlobRequestOptions, OperationContext) create} method or
+     * BlobRequestOptions, com.microsoft.azure.storage.OperationContext) create} method or
      * {@link #uploadPermissions(BlobContainerPermissions) uploadPermissions} method.
      * @param publicAccess
      *            A <code>{@link BlobContainerPublicAccessType}</code> object

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/BlobInputStream.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/BlobInputStream.java
@@ -337,7 +337,7 @@ else if (numberOfBytesRead == 0) {
      * elements <code>b[0]</code> through <code>b[k-1]</code>, leaving elements <code>b[k]</code> through
      * <code>b[b.length-1]</code> unaffected.
      * 
-     * The <code>read(b) method for class {@link InputStream} has the same effect as:
+     * The <code>read(b)</code> method for class {@link InputStream} has the same effect as:
      * 
      * <code>read(b, 0, b.length)</code>
      * 

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/BlobProperties.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/BlobProperties.java
@@ -304,7 +304,7 @@ public Date getLastModified() {
     /**
      * Gets a value indicating if the tier of the blob has been inferred.
      *
-     * @return A {@Link java.lang.Boolean} object which represents if the blob tier was inferred.
+     * @return A {@link java.lang.Boolean} object which represents if the blob tier was inferred.
      */
     public Boolean isBlobTierInferred() { return this.isBlobTierInferredTier; }
 

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/CloudAppendBlob.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/CloudAppendBlob.java
@@ -357,7 +357,7 @@ public Long appendBlock(final InputStream sourceStream, final long length) throw
      *            An {@link OperationContext} object which represents the context for the current operation. This object
      *            is used to track requests to the storage service, and to provide additional runtime information about
      *            the operation.
-     * @return The offset at which the block was appended.</returns>
+     * @return The offset at which the block was appended.
      * @throws IOException
      *             If an I/O exception occurred.
      * @throws StorageException

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/CloudBlob.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/CloudBlob.java
@@ -1549,7 +1549,7 @@ protected final int downloadRangeInternal(final long blobOffset, final Long leng
      *            A <code>byte</code> array which represents the buffer to which the blob bytes are downloaded.
      * @param bufferOffset
      *            An <code>int</code> which represents the byte offset to use as the starting point for the target.
-     * @returns The total number of bytes read into the buffer.
+     * @return The total number of bytes read into the buffer.
      * 
      * @throws StorageException
      */
@@ -1582,7 +1582,7 @@ public final int downloadRangeToByteArray(final long offset, final Long length,
      *            An {@link OperationContext} object that represents the context for the current operation. This object
      *            is used to track requests to the storage service, and to provide additional runtime information about
      *            the operation.
-     * @returns The total number of bytes read into the buffer.
+     * @return The total number of bytes read into the buffer.
      * 
      * @throws StorageException
      *             If a storage service error occurred.

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/CloudBlobClient.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/CloudBlobClient.java
@@ -136,7 +136,7 @@ public CloudBlobContainer getContainerReference(final String containerName) thro
     /**
      * Returns the value for the default delimiter used for cloud blob directories. The default is '/'.
      * 
-     * @return A <code>String<code> which represents the value for the default delimiter.
+     * @return A <code>String</code> which represents the value for the default delimiter.
      */
     public String getDirectoryDelimiter() {
         return this.directoryDelimiter;

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/SubStream.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/blob/SubStream.java
@@ -60,7 +60,6 @@ public class SubStream extends InputStream {
      * @param streamLength The length of the substream.
      * @param lock         An intrinsic lock to ensure thread-safe, concurrent operations
      *                     on substream instances wrapping the same InputStream.
-     * @throws Exception
      */
     public SubStream(InputStream source, long startIndex, long streamLength, Object lock)  {
         if (startIndex < 0 || streamLength < 1) {

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/file/CloudFileDirectory.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/file/CloudFileDirectory.java
@@ -764,11 +764,6 @@ public Iterable<ListFileItem> listFilesAndDirectories() {
      * 
      * @return An enumerable collection of {@link ListFileItem} objects that represent the file and directory items in
      *         this directory.
-     * 
-     * @throws StorageException
-     *             If a storage service error occurred.
-     * @throws URISyntaxException
-     *             If the resource URI is invalid.
      */
     @DoesServiceRequest
     public Iterable<ListFileItem> listFilesAndDirectories(FileRequestOptions options, OperationContext opContext) {
@@ -791,11 +786,6 @@ public Iterable<ListFileItem> listFilesAndDirectories(FileRequestOptions options
      * 
      * @return An enumerable collection of {@link ListFileItem} objects that represent the file and directory items in
      *         this directory.
-     * 
-     * @throws StorageException
-     *             If a storage service error occurred.
-     * @throws URISyntaxException
-     *             If the resource URI is invalid.
      */
     @DoesServiceRequest
     public Iterable<ListFileItem> listFilesAndDirectories(

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/file/CloudFileShare.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/file/CloudFileShare.java
@@ -155,9 +155,7 @@ public CloudFileShare(final StorageUri storageUri) throws StorageException {
      *            A <code>java.net.URI</code> object that represents the absolute URI of the share.
      * @param credentials
      *            A {@link StorageCredentials} object used to authenticate access.
-     * @param snapshotID
-     *            A <code>String</code> that represents the snapshot version, if applicable.
-     * 
+     *
      * @throws StorageException
      *             If a storage service error occurred.
      */
@@ -172,8 +170,6 @@ public CloudFileShare(final URI uri, final StorageCredentials credentials/*, Str
      *            A {@link StorageUri} object which represents the absolute StorageUri of the share.
      * @param credentials
      *            A {@link StorageCredentials} object used to authenticate access.
-     * @param snapshotID
-     *            A <code>String</code> that represents the snapshot version, if applicable.
      * @throws StorageException
      *             If a storage service error occurred.
      */
@@ -1511,7 +1507,7 @@ public final String getSnapshot() {
      *
      * @return <code>true</code> if the share is a snapshot, otherwise <code>false</code>.
      *
-     * @see DeleteSnapshotsOption
+     * @see com.microsoft.azure.storage.blob.DeleteSnapshotsOption
      */
     public final boolean isSnapshot() {
         return this.snapshotID != null;

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/file/FileInputStream.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/file/FileInputStream.java
@@ -329,7 +329,7 @@ else if (numberOfBytesRead == 0) {
      * bytes actually read; these bytes will be stored in elements <code>b[0]</code> through <code>b[k-1]</code>,
      * leaving elements <code>b[k]</code> through <code>b[b.length-1]</code> unaffected.
      * 
-     * The <code>read(b) method for class {@link InputStream} has the same effect as:
+     * The <code>read(b)</code> method for class {@link InputStream} has the same effect as:
      * 
      * <code>read(b, 0, b.length)</code>
      * 

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/queue/QueueEncryptionPolicy.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/queue/QueueEncryptionPolicy.java
@@ -83,7 +83,7 @@ public IKey getKey() {
     /**
      * Gets the key resolver used to select the correct key for decrypting existing queue messages.
      * 
-     * @return A resolver that returns an {@link SymmetricKey} given a keyId.
+     * @return A resolver that returns an {@link IKey} given a keyId.
      */
     public IKeyResolver getKeyResolver() {
         return this.keyResolver;

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/table/CloudTableClient.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/table/CloudTableClient.java
@@ -36,6 +36,8 @@
 import com.microsoft.azure.storage.StorageException;
 import com.microsoft.azure.storage.StorageExtendedErrorInformation;
 import com.microsoft.azure.storage.StorageUri;
+import com.microsoft.azure.storage.blob.CloudBlobClient;
+import com.microsoft.azure.storage.blob.BlobRequestOptions;
 import com.microsoft.azure.storage.core.ExecutionEngine;
 import com.microsoft.azure.storage.core.LazySegmentedIterable;
 import com.microsoft.azure.storage.core.SR;
@@ -53,7 +55,7 @@
  * <p>
  * A Table service endpoint is the base URI for Table service resources, including the DNS name of the storage account:
  * <br>
- * <code>&nbsp&nbsp&nbsp&nbsphttp://<em>myaccount</em>.table.core.windows.net</code><br>
+ * <code>&nbsp;&nbsp;&nbsp;&nbsp;http://<em>myaccount</em>.table.core.windows.net</code><br>
  * For more information, see the MSDN topic <a
  * href="http://msdn.microsoft.com/en-us/library/azure/dd179360.aspx">Addressing Table Service Resources</a>.
  * <p>

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/table/EdmType.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/table/EdmType.java
@@ -35,7 +35,7 @@
  * <a href="http://www.odata.org/developers/protocols/overview">OData Protocol Overview</a>.
  * <p>
  * The Abstract Type System used to define the primitive types supported by OData is defined in detail in <a
- * href="http://msdn.microsoft.com/en-us/library/dd541474.aspx">[MC-CSDL] (section 2.2.1).
+ * href="http://msdn.microsoft.com/en-us/library/dd541474.aspx">[MC-CSDL] (section 2.2.1)</a>.
  */
 public enum EdmType {
     /**

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/table/Encrypt.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/table/Encrypt.java
@@ -26,7 +26,7 @@
  * annotation to specify whether to encrypt the data stored by a setter method or decrypt the data retrieved by a getter
  * method in a class implementing {@link TableEntity}.
  * 
- * @see {@link Ignore}
+ * @see Ignore
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/table/EntityProperty.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/table/EntityProperty.java
@@ -393,7 +393,7 @@ public boolean getIsNull() {
      * Gets the class type of the {@link EntityProperty}.
      * 
      * @return
-     *         The <code>Class<?></code> of the {@link EntityProperty}.
+     *         The <code>Class&lt;?&gt;</code> of the {@link EntityProperty}.
      */
     public Class<?> getType() {
         return this.type;

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/table/TableEncryptionPolicy.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/table/TableEncryptionPolicy.java
@@ -88,7 +88,7 @@ public IKey getKey() {
     /**
      * Gets the key resolver used to select the correct key for decrypting existing table entities.
      * 
-     * @return A resolver that returns an {@link SymmetricKey} given a keyId.
+     * @return A resolver that returns an {@link IKey} given a keyId.
      */
     public IKeyResolver getKeyResolver() {
         return this.keyResolver;

diff --git a/microsoft-azure-storage/src/com/microsoft/azure/storage/table/TableQuery.java b/microsoft-azure-storage/src/com/microsoft/azure/storage/table/TableQuery.java
@@ -43,10 +43,10 @@
  * <p>
  * As an example, you could construct a table query using fluent syntax:
  * <p>
- * <code>TableQuery&ltTableServiceEntity> myQuery = TableQuery.from("Products", DynamicTableEntity.class)<br>
- * &nbsp&nbsp&nbsp&nbsp.where("(PartitionKey eq 'ProductsMNO') and (RowKey ge 'Napkin')")<br>
- * &nbsp&nbsp&nbsp&nbsp.take(25)<br>
- * &nbsp&nbsp&nbsp&nbsp.select(new String[] {"InventoryCount"});</code>
+ * <code>TableQuery&lt;TableServiceEntity&gt; myQuery = TableQuery.from("Products", DynamicTableEntity.class)<br>
+ * &nbsp;&nbsp;&nbsp;&nbsp;.where("(PartitionKey eq 'ProductsMNO') and (RowKey ge 'Napkin')")<br>
+ * &nbsp;&nbsp;&nbsp;&nbsp;.take(25)<br>
+ * &nbsp;&nbsp;&nbsp;&nbsp;.select(new String[] {"InventoryCount"});</code>
  * <p>
  * This example creates a query on the "Products" table for all entities where the PartitionKey value is "ProductsMNO"
  * and the RowKey value is greater than or equal to "Napkin" and requests the first 25 matching entities, selecting only
@@ -597,7 +597,7 @@ public void setColumns(final String[] columns) {
      * constant. The PartitionKey and RowKey property values are <code>String</code> types for comparison purposes. For
      * example, to query all entities with a PartitionKey value of "AccessLogs" on table query <code>myQuery</code>:
      * <p>
-     * <code>&nbsp&nbsp&nbsp&nbspmyQuery.setFilterString("PartitionKey eq 'AccessLogs'");</code>
+     * <code>&nbsp;&nbsp;&nbsp;&nbsp;myQuery.setFilterString("PartitionKey eq 'AccessLogs'");</code>
      * <p>
      * The values that may be used in table queries are explained in more detail in the MSDN topic
      * 
@@ -676,7 +676,7 @@ public TableQuery<T> take(final Integer take) {
      * PartitionKey and RowKey property values are <code>String</code> types for comparison purposes. For example, to
      * query all entities with a PartitionKey value of "AccessLogs" on table query <code>myQuery</code>:
      * <p>
-     * <code>&nbsp&nbsp&nbsp&nbspmyQuery = myQuery.where("PartitionKey eq 'AccessLogs'");</code>
+     * <code>&nbsp;&nbsp;&nbsp;&nbsp;myQuery = myQuery.where("PartitionKey eq 'AccessLogs'");</code>
      * <p>
      * The values that may be used in table queries are explained in more detail in the MSDN topic
      *