Minor docs fix (#281)

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

* Fix last remaining javadoc issues - now javadoc can be successfully generated.

* Fix merge mistake

* Fixes for JavaDoc errors. Most of them are in the .core.* package, but even still, it helps to ensure that build tools that ignore maven directives to ignore packages do not error-out.

Author: JonathanGiles

microsoft-azure-storage/src/com/microsoft/azure/storage/blob/BlobProperties.java

@@ -631,7 +631,7 @@ protected void setStandardBlobTier(StandardBlobTier standardBlobTier) {
     /**
      * Sets whether the blob tier is inferred.
      * @param isBlobTierInferredTier
-     *      A {@Link java.lang.Boolean} which specifies if the blob tier is inferred.
+     *      A {@link java.lang.Boolean} which specifies if the blob tier is inferred.
      */
     protected void setBlobTierInferred(Boolean isBlobTierInferredTier) {
         this.isBlobTierInferredTier = isBlobTierInferredTier;
@@ -649,7 +649,7 @@ protected void setTierChangeTime(Date tierChangeTime) {
     /**
      * Sets the rehydration status of the blob.
      * @param rehydrationStatus
-     *      A {@Link RehydrationStatus} which specifies the rehydration status of the blob.
+     *      A {@link RehydrationStatus} which specifies the rehydration status of the blob.
      */
     protected void setRehydrationStatus(RehydrationStatus rehydrationStatus) {
         this.rehydrationStatus = rehydrationStatus;

microsoft-azure-storage/src/com/microsoft/azure/storage/blob/CloudBlob.java

@@ -1609,7 +1609,7 @@ public void recoveryAction(OperationContext context) throws IOException {
      *            A {@link BlobRequestOptions} object that specifies any additional options for the request.
      * @param opContext
      *            An {@link OperationContext} object used to track the execution of the operation.
-     * @returns The total number of bytes read into the buffer.
+     * @return The total number of bytes read into the buffer.
      * 
      * @throws StorageException
      *             an exception representing any error which occurred during the operation.

microsoft-azure-storage/src/com/microsoft/azure/storage/core/ListResponse.java

@@ -24,7 +24,7 @@ public class ListResponse<T> {
     public static final String ENUMERATION_RESULTS = "EnumerationResults";
 
     /**
-     * Holds the ArrayList<T> of results.
+     * Holds the ArrayList&lt;T&gt; of results.
      */
     protected ArrayList<T> results = new ArrayList<T>();
 
@@ -49,9 +49,9 @@ public class ListResponse<T> {
     protected String prefix;
 
     /**
-     * Gets the ArrayList<T> of the results.
+     * Gets the ArrayList&lt;T&gt; of the results.
      * 
-     * @return the ArrayList<T> of results
+     * @return the ArrayList&lt;T&gt; of results
      */
     public ArrayList<T> getResults() {
         return this.results;
@@ -94,7 +94,7 @@ public String getPrefix() {
     }
 
     /**
-     * Sets the ArrayList<T> of the results
+     * Sets the ArrayList&lt;T&gt; of the results
      * 
      * @param results
      *            the results to set

microsoft-azure-storage/src/com/microsoft/azure/storage/core/PathUtility.java

@@ -98,8 +98,8 @@ public static URI addToQuery(final URI resourceURI, final String queryString) th
      * 
      * @param uriList
      *            The base Uri.
-     * @param relativeOrAbslouteUri
-     *            The relative or absloute URI.
+     * @param relativeOrAbsoluteUri
+     *            The relative or absolute URI.
      * @return The appended Uri.
      * @throws URISyntaxException
      */
@@ -113,8 +113,8 @@ public static StorageUri appendPathToUri(final StorageUri uriList, final String
      * 
      * @param uriList
      *            The base Uri.
-     * @param relativeOrAbslouteUri
-     *            The relative or absloute URI.
+     * @param relativeOrAbsoluteUri
+     *            The relative or absolute URI.
      * @return The appended Uri.
      * @throws URISyntaxException
      */
@@ -127,9 +127,9 @@ public static StorageUri appendPathToUri(final StorageUri uriList, final String
     /**
      * Appends a path to a URI correctly using "/" as separator.
      * 
-     * @param uriList
+     * @param uri
      *            The base Uri.
-     * @param relativeOrAbslouteUri
+     * @param relativeOrAbsoluteUri
      *            The relative or absloute URI.
      * @return The appended Uri.
      * @throws URISyntaxException
@@ -421,7 +421,7 @@ public static String getServiceClientBaseAddress(final URI address, final boolea
     /**
      * Get the service client address from a complete Uri.
      * 
-     * @param address
+     * @param addressUri
      *            Complete address of the resource.
      * @param usePathStyleUris
      *            a value indicating if the address is a path style uri.
@@ -440,7 +440,7 @@ public static StorageUri getServiceClientBaseAddress(final StorageUri addressUri
      * 
      * @param parseString
      *            the string to parse
-     * @return a HashMap<String, String[]> of the key values.
+     * @return a HashMap&lt;String, String[]&gt; of the key values.
      * @throws StorageException
      */
     public static HashMap<String, String[]> parseQueryString(String parseString) throws StorageException {

microsoft-azure-storage/src/com/microsoft/azure/storage/core/SharedAccessSignatureHelper.java

@@ -45,15 +45,10 @@ public class SharedAccessSignatureHelper {
      * 
      * @param policy
      *            The shared access policy to hash.
-     * @param ipRange
-     *            An optional range of IP addresses.
-     * @param protocols
-     *            An optional restriction of allowed protocols.
      * @param signature
      *            The signature to use.
      *            
      * @return The finished query builder
-     * @throws InvalidKeyException
      * @throws StorageException
      */
     public static UriQueryBuilder generateSharedAccessSignatureForAccount(
@@ -214,10 +209,6 @@ public static UriQueryBuilder generateSharedAccessSignatureForTable(
      *            The name of the account to use for the SAS.
      * @param policy
      *            The shared access policy to hash.
-     * @param ipRange
-     *            An optional range of IP addresses.
-     * @param protocols
-     *            An optional restriction of allowed protocols.
      * @param creds
      *            The {@link StorageCredentials} associated with the object.
      *            
@@ -576,7 +567,7 @@ private static UriQueryBuilder generateSharedAccessSignatureHelper(
      * @param stringToSign
      *            The string to decode and hash
      * @param creds
-     *            Reference to the {@link StorageCredentials.}.
+     *            Reference to the {@link StorageCredentials}.
      * 
      * @return The signature hash embedded inside the Shared Access Signature.
      *         
@@ -605,8 +596,6 @@ private static String generateSharedAccessSignatureHashHelper(String stringToSig
      *            The range of IP addresses to hash.
      * @param protocols
      *            The Internet protocols to hash.
-     * @param headers
-     *            The optional header values to set for a blob or file accessed with this shared access signature.
      * @param accessPolicyIdentifier
      *            An optional identifier for the policy.
      *            

microsoft-azure-storage/src/com/microsoft/azure/storage/core/StorageRequest.java

@@ -301,8 +301,6 @@ public final boolean isNonExceptionedRetryableFailure() {
     /**
      * Returns either the held exception from the operation if it is set, otherwise the translated exception.
      * 
-     * @param request
-     *            the reference to the HttpURLConnection for the operation.
      * @param opContext
      *            an object used to track the execution of the operation
      * @return the exception to throw.
@@ -508,8 +506,8 @@ public void setRequestLocationMode(RequestLocationMode requestLocationMode) {
     }
 
     /**
-     * @param storageLocation
-     *            the storageLocation value
+     * @param currentLocation
+     *            the currentLocation value
      */
     public void setCurrentLocation(StorageLocation currentLocation) {
         this.currentLocation = currentLocation;
@@ -594,12 +592,14 @@ public void setHeaders(HttpURLConnection connection, P parentObject, OperationCo
     /**
      * Pre-Stream Retrieval function.
      * 
-     * @param command
-     *            StorageCommand for the operation.
      * @param parentObject
      *            Parent object, i.e. CloudBlobContainer for downloadAttributes etc.
      * @param client
      *            The service client.
+     * @param context
+     *            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.
      * @return an Object of the expected result's type.
      * @throws Exception
      */

microsoft-azure-storage/src/com/microsoft/azure/storage/core/Utility.java

@@ -548,9 +548,6 @@ private static boolean isHostDnsName(URI uri) {
     /**
      * Reads character data for the Etag element from an XML stream reader.
      * 
-     * @param xmlr
-     *            An <code>XMLStreamReader</code> object that represents the source XML stream reader.
-     * 
      * @return A <code>String</code> that represents the character data for the Etag element.
      */
     public static String formatETag(final String etag) {
@@ -1319,7 +1316,7 @@ public static StreamMd5AndLength writeToOutputStream(final InputStream sourceStr
      * @param request
      *            Used by download resume to set currentRequestByteCount on the request. Otherwise, null is always used.
      * @param descriptor
-     *                A {@Link StreamMd5AndLength} object to append to in the case of recovery action or null if this is not called
+     *                A {@link StreamMd5AndLength} object to append to in the case of recovery action or null if this is not called
      *                from a recovery. This value needs to be passed for recovery in case part of the body has already been read,
      *                the recovery will attempt to download the remaining bytes but will do MD5 validation on the originally
      *                requested range size.

microsoft-azure-storage/src/com/microsoft/azure/storage/file/CloudFile.java

@@ -2670,10 +2670,6 @@ public void upload(final InputStream sourceStream, final long length, final Acce
      * 
      * @param resourceAddress
      *            A {@link StorageUri} object which represents the resource URI.
-     * @param delimiter
-     *            A <code>String</code> which specifies the directory delimiter to use.
-     * @param usePathStyleUris
-     *            A <code>Boolean</code> which specifies whether path style URIs are used.
      * @param share
      *            A {@link CloudFileShare} object which represents the file share.
      * 

microsoft-azure-storage/src/com/microsoft/azure/storage/table/EntityProperty.java

@@ -123,8 +123,8 @@ else if (type.equals(Long.class)) {
      * 
      * @param value
      *            The <code>Object</code> to convert to a string and store.
-     * @param edmType
-     *            The <code>Class<?></code> type of the value to construct.
+     * @param type
+     *            The <code>Class&lt;?&gt;</code> type of the value to construct.
      */
     protected EntityProperty(final Object value, final Class<?> type) {        
         if (type.equals(byte[].class)) {

microsoft-azure-storage/src/com/microsoft/azure/storage/table/TableServiceEntity.java

@@ -492,8 +492,8 @@ private static ConcurrentHashMap<Class<?>, HashMap<String, PropertyPair>> initia
      * entities are deserialized and the payload does not include JSON metadata.
      * 
      * @return
-     *         The <code>ConcurrentHashMap<Class<?>, HashMap<String, PropertyPair>></code> representing the known entity
-     *         types and their reflected entity dictionaries
+     *         The <code>ConcurrentHashMap&lt;Class&lt;?&gt;, HashMap&lt;String, PropertyPair&gt;&gt;</code> representing
+     *         the known entity types and their reflected entity dictionaries
      */
     protected static ConcurrentHashMap<Class<?>, HashMap<String, PropertyPair>> getReflectedEntityCache() {
         return TableServiceEntity.reflectedEntityCache;