From da3bf0562925e17b78aaeacdfc126403d4df2a1c Mon Sep 17 00:00:00 2001 From: koros Date: Mon, 18 Nov 2024 18:55:44 +0300 Subject: [PATCH] add comments and documentation info. to Writers/HTTP/CodeClassDeclarationWriter.cs --- .../HTTP/CodeClassDeclarationWriter.cs | 121 ++++++++++++++---- 1 file changed, 94 insertions(+), 27 deletions(-) diff --git a/src/Kiota.Builder/Writers/HTTP/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/HTTP/CodeClassDeclarationWriter.cs index 72ecbd1c6d..09b1bca791 100644 --- a/src/Kiota.Builder/Writers/HTTP/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/HTTP/CodeClassDeclarationWriter.cs @@ -12,40 +12,49 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu ArgumentNullException.ThrowIfNull(codeElement); ArgumentNullException.ThrowIfNull(writer); - if (codeElement.Parent is CodeClass codeClass && codeClass.IsOfKind(CodeClassKind.RequestBuilder)) + if (codeElement.Parent is CodeClass requestBuilderClass && requestBuilderClass.IsOfKind(CodeClassKind.RequestBuilder)) { // Write short description - conventions.WriteShortDescription(codeClass, writer); + conventions.WriteShortDescription(requestBuilderClass, writer); writer.WriteLine(); // Write the baseUrl variable - WriteBaseUrl(codeClass, writer); + WriteBaseUrl(requestBuilderClass, writer); // Extract and write the URL template - WriteUrlTemplate(codeElement, writer); + WriteUrlTemplate(requestBuilderClass, writer); // Write path parameters - WritePathParameters(codeElement, writer); + WritePathParameters(requestBuilderClass, writer); // Write all query parameter variables - WriteQueryParameters(codeElement, writer); + WriteQueryParameters(requestBuilderClass, writer); // Write all HTTP methods GET, POST, PUT, DELETE e.t.c - WriteHttpMethods(codeElement, writer); + WriteHttpMethods(requestBuilderClass, writer); } } - private static void WriteBaseUrl(CodeClass codeClass, LanguageWriter writer) + /// + /// Writes the base URL for the given request builder class to the writer. + /// + /// The request builder class containing the base URL property. + /// The language writer to write the base URL to. + private static void WriteBaseUrl(CodeClass requestBuilderClass, LanguageWriter writer) { - var baseUrl = codeClass.Properties.FirstOrDefault(property => property.Name.Equals("BaseUrl", StringComparison.OrdinalIgnoreCase))?.DefaultValue; + // Retrieve the base URL property from the request builder class + var baseUrl = requestBuilderClass.Properties + .FirstOrDefault(property => property.Name.Equals("BaseUrl", StringComparison.OrdinalIgnoreCase))?.DefaultValue; + + // Write the base URL variable to the writer writer.WriteLine($"# baseUrl"); writer.WriteLine($"@baseUrl = {baseUrl}"); writer.WriteLine(); } - private static void WriteUrlTemplate(CodeElement codeElement, LanguageWriter writer) + private static void WriteUrlTemplate(CodeClass requestBuilderClass, LanguageWriter writer) { - var urlTemplateProperty = codeElement.Parent? + var urlTemplateProperty = requestBuilderClass .GetChildElements(true) .OfType() .FirstOrDefault(property => property.IsOfKind(CodePropertyKind.UrlTemplate)); @@ -56,29 +65,42 @@ private static void WriteUrlTemplate(CodeElement codeElement, LanguageWriter wri writer.WriteLine(); } - private static void WritePathParameters(CodeElement codeElement, LanguageWriter writer) + /// + /// Writes the path parameters for the given request builder class to the writer. + /// + /// The request builder class containing the path parameters. + /// The language writer to write the path parameters to. + private static void WritePathParameters(CodeClass requestBuilderClass, LanguageWriter writer) { // Retrieve all the path variables except the generic path parameter named "pathParameters" - var pathParameters = codeElement.Parent? + var pathParameters = requestBuilderClass .GetChildElements(true) .OfType() .Where(property => property.IsOfKind(CodePropertyKind.PathParameters) && !property.Name.Equals("pathParameters", StringComparison.OrdinalIgnoreCase)) .ToList(); + // Write each path parameter property pathParameters?.ForEach(prop => { WriteHttpParameterProperty(prop, writer); }); } - private static void WriteQueryParameters(CodeElement codeElement, LanguageWriter writer) + /// + /// Writes the query parameters for the given request builder class to the writer. + /// + /// The request builder class containing the query parameters. + /// The language writer to write the query parameters to. + private static void WriteQueryParameters(CodeClass requestBuilderClass, LanguageWriter writer) { - var queryParameterClasses = codeElement.Parent? + // Retrieve all the query parameter classes + var queryParameterClasses = requestBuilderClass .GetChildElements(true) .OfType() .Where(element => element.IsOfKind(CodeClassKind.QueryParameters)) .ToList(); + // Write each query parameter property queryParameterClasses?.ForEach(paramCodeClass => { var queryParams = paramCodeClass @@ -93,47 +115,81 @@ private static void WriteQueryParameters(CodeElement codeElement, LanguageWriter }); } + /// + /// Writes the HTTP parameter property to the writer. + /// + /// The property to write. + /// The language writer to write the property to. private static void WriteHttpParameterProperty(CodeProperty property, LanguageWriter writer) { if (!string.IsNullOrEmpty(property.Name)) { + // Write the property documentation as a comment writer.WriteLine($"# {property.Documentation.DescriptionTemplate}"); + + // Write the property name and an assignment placeholder writer.WriteLine($"@{property.Name.ToFirstCharacterLowerCase()} = "); + + // Write an empty line for separation writer.WriteLine(); } } - private static void WriteHttpMethods(CodeElement codeElement, LanguageWriter writer) + /// + /// Writes the HTTP methods (GET, POST, PATCH, DELETE, e.t.c) for the given request builder class to the writer. + /// + /// The request builder class containing the HTTP methods. + /// The language writer to write the HTTP methods to. + private static void WriteHttpMethods(CodeClass requestBuilderClass, LanguageWriter writer) { - var httpMethods = codeElement.Parent? + // Retrieve all the HTTP methods of kind RequestExecutor + var httpMethods = requestBuilderClass .GetChildElements(true) .OfType() .Where(element => element.IsOfKind(CodeMethodKind.RequestExecutor)) .ToList(); + // Write each HTTP method httpMethods?.ForEach(method => { + // Write the method documentation as a comment writer.WriteLine($"# {method.Documentation.DescriptionTemplate}"); - writer.WriteLine($"{method.Name.ToUpperInvariant()} {GetUrlTemplate(codeElement)}"); + // Write the method name and URL template + writer.WriteLine($"{method.Name.ToUpperInvariant()} {GetUrlTemplate(requestBuilderClass)}"); + + // Write the request body if present WriteRequestBody(method, writer); + // Write an empty line for separation writer.WriteLine(); writer.WriteLine("###"); writer.WriteLine(); }); } - private static string GetUrlTemplate(CodeElement codeElement) + /// + /// Retrieves the URL template for the given request builder class. + /// + /// The request builder class containing the URL template property. + /// The URL template as a string, or an empty string if not found. + private static string GetUrlTemplate(CodeClass requestBuilderClass) { - var urlTemplateProperty = codeElement.Parent? + // Retrieve the URL template property from the request builder class + var urlTemplateProperty = requestBuilderClass .GetChildElements(true) .OfType() .FirstOrDefault(property => property.IsOfKind(CodePropertyKind.UrlTemplate)); + // Return the URL template or an empty string if not found return urlTemplateProperty?.DefaultValue ?? string.Empty; } + /// + /// Writes the request body for the given method to the writer. + /// + /// The method containing the request body. + /// The language writer to write the request body to. private static void WriteRequestBody(CodeMethod method, LanguageWriter writer) { // If there is a request body, write it @@ -144,7 +200,7 @@ private static void WriteRequestBody(CodeMethod method, LanguageWriter writer) writer.WriteLine(); writer.WriteLine($"Content-Type: {method.RequestBodyContentType}"); - // loop through the properties of the request body and write a JSON object + // Loop through the properties of the request body and write a JSON object if (requestBody.Type is CodeType ct && ct.TypeDefinition is CodeClass requestBodyClass) { writer.WriteLine("{"); @@ -154,9 +210,15 @@ private static void WriteRequestBody(CodeMethod method, LanguageWriter writer) writer.WriteLine("}"); } } - private static void WriteProperties(CodeClass codeClass, LanguageWriter writer) + + /// + /// Writes the properties of the given request body class to the writer. + /// + /// The request body class containing the properties. + /// The language writer to write the properties to. + private static void WriteProperties(CodeClass requestBodyClass, LanguageWriter writer) { - var properties = codeClass.Properties.Where(prop => prop.IsOfKind(CodePropertyKind.Custom)).ToList(); + var properties = requestBodyClass.Properties.Where(prop => prop.IsOfKind(CodePropertyKind.Custom)).ToList(); for (int i = 0; i < properties.Count; i++) { var prop = properties[i]; @@ -188,20 +250,25 @@ private static void WriteProperties(CodeClass codeClass, LanguageWriter writer) } // If the class extends another class, write properties of the base class - if (codeClass.StartBlock.Inherits?.TypeDefinition is CodeClass baseClass) + if (requestBodyClass.StartBlock.Inherits?.TypeDefinition is CodeClass baseClass) { WriteProperties(baseClass, writer); } } - private static string GetDefaultValueForProperty(CodeProperty prop) + /// + /// Gets the default value for the given property. + /// + /// The property to get the default value for. + /// The default value as a string. + private static string GetDefaultValueForProperty(CodeProperty codeProperty) { - return prop.Type.Name switch + return codeProperty.Type.Name switch { "int" or "integer" => "0", "string" => "\"string\"", "bool" or "boolean" => "false", - _ when prop.Type is CodeType enumType && enumType.TypeDefinition is CodeEnum enumDefinition => + _ when codeProperty.Type is CodeType enumType && enumType.TypeDefinition is CodeEnum enumDefinition => enumDefinition.Options.FirstOrDefault()?.Name is string enumName ? $"\"{enumName}\"" : "null", _ => "null" };