- adds support for indexer parameter description

Signed-off-by: Vincent Biret <[email protected]>
microsoft · Aug 4, 2023 · c7ecd1d · c7ecd1d
1 parent 61a370b
commit c7ecd1d
Show file tree

Hide file tree

Showing 5 changed files with 27 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added support for indexer parameter description. [#2978](https://github.com/microsoft/kiota/issues/2978)
+
 ### Changed
 
 ## [1.5.0] - 2023-08-04

diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs
@@ -971,7 +971,7 @@ private IEnumerable<CodeType> GetUnmappedTypeDefinitions(CodeElement codeElement
         };
     }
     private static CodeType DefaultIndexerParameterType => new() { Name = "string", IsExternal = true };
-    private CodeType GetIndexerParameterType(OpenApiUrlTreeNode currentNode, OpenApiUrlTreeNode parentNode)
+    private CodeParameter GetIndexerParameterType(OpenApiUrlTreeNode currentNode, OpenApiUrlTreeNode parentNode)
     {
         var parameterName = currentNode.Path[parentNode.Path.Length..].Trim('\\', ForwardSlash, '{', '}');
         var parameter = currentNode.PathItems.TryGetValue(Constants.DefaultOpenApiLabel, out var pathItem) ? pathItem.Parameters
@@ -987,9 +987,19 @@ private CodeType GetIndexerParameterType(OpenApiUrlTreeNode currentNode, OpenApi
             _ => GetPrimitiveType(parameter.Schema),
         } ?? DefaultIndexerParameterType;
         type.IsNullable = false;
-        return type;
+        var result = new CodeParameter
+        {
+            Type = type,
+            SerializationName = currentNode.Segment.SanitizeParameterNameForUrlTemplate(),
+            Name = currentNode.Segment.CleanupSymbolName(),
+            Documentation = new()
+            {
+                Description = parameter?.Description.CleanupDescription() is string description && !string.IsNullOrEmpty(description) ? description : "Unique identifier of the item",
+            },
+        };
+        return result;
     }
-    private CodeIndexer[] CreateIndexer(string childIdentifier, string childType, CodeType parameterType, OpenApiUrlTreeNode currentNode, OpenApiUrlTreeNode parentNode)
+    private CodeIndexer[] CreateIndexer(string childIdentifier, string childType, CodeParameter parameter, OpenApiUrlTreeNode currentNode, OpenApiUrlTreeNode parentNode)
     {
         logger.LogTrace("Creating indexer {Name}", childIdentifier);
         var result = new List<CodeIndexer> { new CodeIndexer
@@ -1002,15 +1012,10 @@ private CodeIndexer[] CreateIndexer(string childIdentifier, string childType, Co
             ReturnType = new CodeType { Name = childType },
             PathSegment = parentNode.GetNodeNamespaceFromPath(string.Empty).Split('.').Last(),
             Deprecation = currentNode.GetDeprecationInformation(),
-            IndexParameter = new() {
-                Type = parameterType,
-                SerializationName = currentNode.Segment.SanitizeParameterNameForUrlTemplate(),
-                Name = currentNode.Segment.CleanupSymbolName(),
-                //TODO description
-            }
+            IndexParameter = parameter,
         }};
 
-        if (!"string".Equals(parameterType.Name, StringComparison.OrdinalIgnoreCase))
+        if (!"string".Equals(parameter.Type.Name, StringComparison.OrdinalIgnoreCase))
         { // adding a second indexer for the string version of the parameter so we keep backward compatibility
             //TODO remove for v2
             var backCompatibleValue = (CodeIndexer)result[0].Clone();

diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs
@@ -13,6 +13,7 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr
         if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class");
         var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement);
         conventions.WriteShortDescription(codeElement.Documentation.Description, writer);
+        writer.WriteLine($"{conventions.DocCommentPrefix}<param name=\"position\">{codeElement.IndexParameter.Documentation.Description.CleanupXMLString()}</param>");
         conventions.WriteDeprecationAttribute(codeElement, writer);
         writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{");
         if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp)

diff --git a/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs b/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs
@@ -5711,7 +5711,8 @@ public async Task IndexerAndRequestBuilderNamesMatch()
         var collectionRequestBuilder = collectionRequestBuilderNamespace.FindChildByName<CodeClass>("postsRequestBuilder");
         var collectionIndexer = collectionRequestBuilder.Indexer;
         Assert.NotNull(collectionIndexer);
-        Assert.Equal("string", collectionIndexer.IndexParameter.Type.Name);
+        Assert.Equal("string", collectionIndexer.IndexParameter.Type.Name, StringComparer.OrdinalIgnoreCase);
+        Assert.Equal("Unique identifier of the item", collectionIndexer.IndexParameter.Documentation.Description, StringComparer.OrdinalIgnoreCase);
         Assert.False(collectionIndexer.Deprecation.IsDeprecated);
         var itemRequestBuilderNamespace = codeModel.FindNamespaceByName("ApiSdk.me.posts.item");
         Assert.NotNull(itemRequestBuilderNamespace);
@@ -5735,6 +5736,7 @@ public async Task IndexerTypeIsAccurateAndBackwardCompatibleIndexersAreAdded()
         - name: post-id
           in: path
           required: true
+          description: The id of the pet to retrieve
           schema:
             type: integer
             format: int32
@@ -5765,6 +5767,7 @@ public async Task IndexerTypeIsAccurateAndBackwardCompatibleIndexersAreAdded()
         var collectionIndexer = collectionRequestBuilder.Indexer;
         Assert.NotNull(collectionIndexer);
         Assert.Equal("integer", collectionIndexer.IndexParameter.Type.Name);
+        Assert.Equal("The id of the pet to retrieve", collectionIndexer.IndexParameter.Documentation.Description, StringComparer.OrdinalIgnoreCase);
         Assert.False(collectionIndexer.IndexParameter.Type.IsNullable);
         Assert.False(collectionIndexer.Deprecation.IsDeprecated);
         var collectionStringIndexer = collectionRequestBuilder.FindChildByName<CodeIndexer>($"{collectionIndexer.Name}-string");

diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs
@@ -41,6 +41,10 @@ public CodeIndexerWriterTests()
                     Name = "string",
                 },
                 SerializationName = "id",
+                Documentation = new()
+                {
+                    Description = "some description"
+                }
             }
         };
         parentClass.AddIndexer(indexer);
@@ -75,6 +79,7 @@ public void WritesIndexer()
         Assert.Contains("RequestAdapter", result);
         Assert.Contains("PathParameters", result);
         Assert.Contains("id\", position", result);
+        Assert.Contains("some description", result);
         Assert.Contains("public SomeRequestBuilder this[string position]", result);
         AssertExtensions.CurlyBracesAreClosed(result);
     }