Merge pull request #124 from microsoftgraph/javadoc-cleanup

Javadoc cleanup

Author: Caitlin Bales (MSFT)

Templates/Java/BaseJavaModel.template.tt

@@ -386,6 +386,15 @@
         }
         return "Void";
     }
+
+	public string MethodParametersJavadocSignature(OdcmMethod method) {
+		var parameterSignatureBuilder = new StringBuilder();
+        foreach (var p in method.Parameters)
+        {
+            parameterSignatureBuilder.AppendFormat("\r\n     * @param {0} the {0}", ParamName(p));
+        }
+        return parameterSignatureBuilder.ToString();
+	}
 
     public string MethodParametersSignature(OdcmMethod method) {
         var parameterSignatureBuilder = new StringBuilder();
@@ -660,7 +669,7 @@ public {1} {2}{3}{4} {{";
                 property.Name,
                 propertyType,
                 property.Name.SanitizePropertyName(property).ToLowerFirstChar(),
-				property.LongDescription);
+				ReplaceInvalidCharacters(property.LongDescription));
         }
         return sb.ToString();
     }
@@ -684,7 +693,7 @@ public {1} {2}{3}{4} {{";
             sb.AppendFormat(
                 format,
                 ParamName(p).SplitCamelCase(),
-				p.LongDescription,
+				ReplaceInvalidCharacters(p.LongDescription),
                 ParamName(p),
                 ParamType(p),
                 ParamName(p).SanitizePropertyName(p).ToLowerFirstChar()
@@ -707,6 +716,7 @@ public {1} {2}{3}{4} {{";
 
     /**
      * Gets the raw representation of this class
+     *
      * @return the raw representation of this class
      */
     public JsonObject getRawObject() {
@@ -715,17 +725,18 @@ public {1} {2}{3}{4} {{";
 
     /**
      * Gets serializer
+     *
      * @return the serializer
      */
     protected ISerializer getSerializer() {
         return serializer;
     }
 
     /**
-     * Sets the raw json object
+     * Sets the raw JSON object
      *
-     * @param serializer The serializer
-     * @param json The json object to set this object to
+     * @param serializer the serializer
+     * @param json the JSON object to set this object to
      */
     public void setRawObject(final ISerializer serializer, final JsonObject json) {
         this.serializer = serializer;
@@ -825,4 +836,15 @@ public {1} {2}{3}{4} {{";
 		//Specifying a return type of "void" throws an error
 	   return string.Empty;
 	}
+
+	/**
+	* Replaces invalid Javadoc characters with HTML
+	*/
+	public string ReplaceInvalidCharacters(string inputString)
+	{
+		if (inputString != null) {
+			return inputString.Replace("<", "&lt;").Replace(">", "&gt;").Replace("&", "&amp;");
+		}
+		return null;
+	}
 #>

Templates/Java/models_generated/IBaseClient.java.tt

@@ -15,17 +15,17 @@ foreach (var prop in model.EntityContainer.Properties)
 #>
 
     /**
-     * Gets the collection of <#=propertyName#> objects.
+     * Gets the collection of <#=propertyName#> objects
      *
-     * @return The request builder for the collection of <#=propertyName#> objects
+     * @return the request builder for the collection of <#=propertyName#> objects
      */
     <#=ITypeCollectionRequestBuilder(prop)#> <#=prop.Name#>();
 
     /**
-     * Gets a single <#=propertyName#>.
+     * Gets a single <#=propertyName#>
      *
-     * @param id The id of the <#=propertyName#> to retrieve.
-     * @return The request builder for the <#=propertyName#> object
+     * @param id the id of the <#=propertyName#> to retrieve
+     * @return the request builder for the <#=propertyName#> object
      */
     <#=ITypeRequestBuilder(prop)#> <#=prop.Name#>(final String id);
 <#
@@ -35,9 +35,9 @@ foreach (var prop in model.EntityContainer.Properties)
 #>
 
     /**
-     * Gets <#=TypeRequestBuilder(c)#>.
+     * Gets the <#=TypeRequestBuilder(c)#>
      *
-     * @return the <#=prop.Projection.Type.GetTypeString()#>.
+     * @return the <#=prop.Projection.Type.GetTypeString()#>
      */
     <#=ITypeRequestBuilder(prop)#> <#=prop.Name#>();
 <#

Templates/Java/requests_extensions/Client.java.tt

@@ -28,7 +28,7 @@ import <#=host.CurrentModel.NamespaceName()#>.logger.*;
 
         /**
          * Sets the serializer
-         * @param serializer The serializer
+         * @param serializer the serializer
          * @return the instance of this builder
          */
         public Builder serializer(final ISerializer serializer) {
@@ -38,7 +38,7 @@ import <#=host.CurrentModel.NamespaceName()#>.logger.*;
 
         /**
          * Sets the httpProvider
-         * @param httpProvider The httpProvider
+         * @param httpProvider the httpProvider
          * @return the instance of this builder
          */
         public Builder httpProvider(final IHttpProvider httpProvider) {
@@ -48,7 +48,7 @@ import <#=host.CurrentModel.NamespaceName()#>.logger.*;
 
         /**
          * Sets the authentication provider
-         * @param authenticationProvider The authentication provider
+         * @param authenticationProvider the authentication provider
          * @return the instance of this builder
          */
         public Builder authenticationProvider(final IAuthenticationProvider authenticationProvider) {
@@ -58,7 +58,7 @@ import <#=host.CurrentModel.NamespaceName()#>.logger.*;
 
         /**
          * Sets the executors
-         * @param executors The executors
+         * @param executors the executors
          * @return the instance of this builder
          */
         public Builder executors(final IExecutors executors) {
@@ -68,7 +68,7 @@ import <#=host.CurrentModel.NamespaceName()#>.logger.*;
 
         /**
          * Sets the logger
-         * @param logger The logger
+         * @param logger the logger
          * @return the instance of this builder
          */
         public Builder logger(final ILogger logger) {
@@ -78,7 +78,7 @@ import <#=host.CurrentModel.NamespaceName()#>.logger.*;
 
         /**
          * Set this builder based on the client configuration
-         * @param clientConfig The client configuration
+         * @param clientConfig the client configuration
          * @return the instance of this builder
          */
         public Builder fromConfig(final IClientConfig clientConfig) {

Templates/Java/requests_extensions/EntityCollectionPage.java.tt

@@ -10,8 +10,8 @@
     /**
      * A collection page for <#=ClassTypeName(c)#>.
      *
-     * @param response The serialized <#=BaseTypeCollectionResponse(c)#> from the service
-     * @param builder The request builder for the next collection page
+     * @param response the serialized <#=BaseTypeCollectionResponse(c)#> from the service
+     * @param builder the request builder for the next collection page
      */
     public <#=TypeCollectionPage(c)#>(final <#=BaseTypeCollectionResponse(c)#> response, final <#=ITypeCollectionRequestBuilder(c)#> builder) {
         super(response, builder);

Templates/Java/requests_extensions/EntityCollectionReferenceRequest.java.tt

@@ -11,9 +11,9 @@
     /**
      * The request for this collection of <#=ClassTypeName(c)#>
      *
-     * @param requestUrl The request url
-     * @param client The service client
-     * @param options The options for this request
+     * @param requestUrl the request URL
+     * @param client     the service client
+     * @param options    the options for this request
      */
     public <#=TypeCollectionReferenceRequest(c)#>(final String requestUrl, final <#=IBaseClientType()#> client, final java.util.List<? extends Option> options) {
         super(requestUrl, client, options);

Templates/Java/requests_extensions/EntityCollectionReferenceRequestBuilder.java.tt

@@ -11,9 +11,9 @@
     /**
      * The request builder for this collection of <#=ClassTypeName(c)#>
      *
-     * @param requestUrl The request url
-     * @param client The service client
-     * @param requestOptions The options for this request
+     * @param requestUrl     the request URL
+     * @param client         the service client
+     * @param requestOptions the options for this request
      */
     public <#=TypeCollectionReferenceRequestBuilder(c)#>(final String requestUrl, final <#=IBaseClientType()#> client, final java.util.List<? extends Option> requestOptions) {
         super(requestUrl, client, requestOptions);

Templates/Java/requests_extensions/EntityCollectionRequest.java.tt

@@ -11,9 +11,9 @@
     /**
      * The request for this collection of <#=ClassTypeName(c)#>
      *
-     * @param requestUrl The request url
-     * @param client The service client
-     * @param requestOptions The options for this request
+     * @param requestUrl     the request URL
+     * @param client         the service client
+     * @param requestOptions the options for this request
      */
     public <#=TypeCollectionRequest(c)#>(final String requestUrl, final <#=IBaseClientType()#> client, final java.util.List<? extends Option> requestOptions) {
         super(requestUrl, client, requestOptions);

Templates/Java/requests_extensions/EntityCollectionRequestBuilder.java.tt

@@ -11,9 +11,9 @@
     /**
      * The request builder for this collection of <#=ClassTypeName(c)#>
      *
-     * @param requestUrl The request url
-     * @param client The service client
-     * @param requestOptions The options for this request
+     * @param requestUrl     the request URL
+     * @param client         the service client
+     * @param requestOptions the options for this request
      */
     public <#=TypeCollectionRequestBuilder(c)#>(final String requestUrl, final <#=IBaseClientType()#> client, final java.util.List<? extends Option> requestOptions) {
         super(requestUrl, client, requestOptions);

Templates/Java/requests_extensions/EntityCollectionWithReferencesPage.java.tt

@@ -10,8 +10,8 @@
     /**
      * A collection page for <#=ClassTypeName(c)#>.
      *
-     * @param response The serialized <#=BaseTypeCollectionResponse(c)#> from the service
-     * @param builder The request builder for the next collection page
+     * @param response the serialized <#=BaseTypeCollectionResponse(c)#> from the service
+     * @param builder  the request builder for the next collection page
      */
     public <#=TypeCollectionWithReferencesPage(c)#>(final <#=BaseTypeCollectionResponse(c)#> response, final <#=ITypeCollectionWithReferencesRequestBuilder(c)#> builder) {
         super(response, builder);

Templates/Java/requests_extensions/EntityCollectionWithReferencesRequest.java.tt

@@ -11,9 +11,9 @@
     /**
      * The request for this collection of <#=ClassTypeName(c)#>
      *
-     * @param requestUrl The request url
-     * @param client The service client
-     * @param requestOptions The options for this request
+     * @param requestUrl     the request URL
+     * @param client         the service client
+     * @param requestOptions the options for this request
      */
     public <#=TypeCollectionWithReferencesRequest(c)#>(final String requestUrl, final <#=IBaseClientType()#> client, final java.util.List<? extends Option> requestOptions) {
         super(requestUrl, client, requestOptions);