feature/docs reference

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Adds description validation rules to help users get the best client experience. [#2019](https://github.com/microsoft/kiota/issues/2019)
+- Adds support for external documentation links on request execution methods. [#2036](https://github.com/microsoft/kiota/issues/2036)
 
 ### Changed
 

src/Kiota.Builder/CodeDOM/CodeDocumentation.cs

@@ -0,0 +1,44 @@
+
+using System;
+
+namespace Kiota.Builder.CodeDOM;
+
+/// <summary>
+/// The documentation information of a code element.
+/// </summary>
+public class CodeDocumentation : ICloneable
+{
+    /// <summary>
+    /// The description of the current element.
+    /// </summary>
+    public string Description
+    {
+        get; set;
+    }
+    /// <summary>
+    /// The external documentation link for this method.
+    /// </summary>
+    public Uri DocumentationLink
+    {
+        get; set;
+    }
+    ///<summary>
+    ///The label for the external documentation link.
+    ///</summary>
+    public string DocumentationLabel
+    {
+        get; set;
+    }
+
+    /// <inheritdoc/>
+    public object Clone()
+    {
+        return new CodeDocumentation {
+            Description = Description?.Clone() as string,
+            DocumentationLink = DocumentationLink == null ? null : new (DocumentationLink.ToString()),
+            DocumentationLabel = DocumentationLabel?.Clone() as string,
+        };
+    }
+    public bool DescriptionAvailable { get => !string.IsNullOrEmpty(Description); }
+    public bool ExternalDocumentationAvailable { get => DocumentationLink != null && !string.IsNullOrEmpty(DocumentationLabel); }
+}

src/Kiota.Builder/CodeDOM/CodeEnum.cs

@@ -7,7 +7,7 @@ public class CodeEnum : CodeBlock<BlockDeclaration, BlockEnd>, IDocumentedElemen
     private readonly HashSet<string> optionsNames = new(StringComparer.OrdinalIgnoreCase); // this structure is used to check if an option name is unique   
     private readonly ConcurrentQueue<CodeEnumOption> OptionsInternal = new (); // this structure is used to maintain the order of the options
     public bool Flags { get; set; }
-    public string Description {get; set;}
+    public CodeDocumentation Documentation { get; set; } = new();
 
     public void AddOption(params CodeEnumOption[] codeEnumOptions)
     {

src/Kiota.Builder/CodeDOM/CodeEnumOption.cs

@@ -3,7 +3,7 @@ namespace Kiota.Builder.CodeDOM;
 public class CodeEnumOption : IDocumentedElement, ITypeDefinition
 {
     public string SerializationName { get; set; }
-    public string Description { get; set; }
+    public CodeDocumentation Documentation { get; set; } = new();
     public string Name { get; set; }
     public CodeElement Parent { get; set; }
 }

src/Kiota.Builder/CodeDOM/CodeIndexer.cs

@@ -12,7 +12,7 @@ public class CodeIndexer : CodeTerminal, IDocumentedElement
         returnType = value;
     }}
     public string SerializationName { get; set; }
-    public string Description {get; set;}
+    public CodeDocumentation Documentation { get; set; } = new();
     /// <summary>
     /// The Path segment to use for the method name when using back-compatible methods.
     /// </summary>

src/Kiota.Builder/CodeDOM/CodeMethod.cs

@@ -82,7 +82,9 @@ public static CodeMethod FromIndexer(CodeIndexer originalIndexer, CodeClass inde
             Access = AccessModifier.Public,
             Kind = CodeMethodKind.IndexerBackwardCompatibility,
             Name = originalIndexer.PathSegment + methodNameSuffix,
-            Description = originalIndexer.Description,
+            Documentation = new () {
+                Description = originalIndexer.Documentation.Description,
+            },
             ReturnType = new CodeType {
                 IsNullable = false,
                 TypeDefinition = indexerClass,
@@ -94,7 +96,9 @@ public static CodeMethod FromIndexer(CodeIndexer originalIndexer, CodeClass inde
             Name = "id",
             Optional = false,
             Kind = CodeParameterKind.Custom,
-            Description = "Unique identifier of the item",
+            Documentation = new() {
+                Description = "Unique identifier of the item",
+            },
             Type = new CodeType {
                 Name = "String",
                 IsNullable = parameterNullable,
@@ -141,7 +145,7 @@ public void ClearParameters()
     public IEnumerable<CodeParameter> Parameters { get => parameters.Values.OrderBy(static x => x, parameterOrderComparer); }
     public bool IsStatic {get;set;}
     public bool IsAsync {get;set;} = true;
-    public string Description {get; set;}
+    public CodeDocumentation Documentation { get; set; } = new();
 
     public PagingInformation PagingInformation
     {
@@ -232,7 +236,6 @@ public object Clone()
             IsAsync = IsAsync,
             Access = Access,
             IsStatic = IsStatic,
-            Description = Description?.Clone() as string,
             RequestBodyContentType = RequestBodyContentType?.Clone() as string,
             BaseUrl = BaseUrl?.Clone() as string,
             AccessedProperty = AccessedProperty,
@@ -244,6 +247,7 @@ public object Clone()
             errorMappings = errorMappings == null ? null : new (errorMappings),
             acceptedResponseTypes = acceptedResponseTypes == null ? null : new (acceptedResponseTypes),
             PagingInformation = PagingInformation?.Clone() as PagingInformation,
+            Documentation = Documentation?.Clone() as CodeDocumentation,
         };
         if(Parameters?.Any() ?? false)
             method.AddParameter(Parameters.Select(x => x.Clone() as CodeParameter).ToArray());

src/Kiota.Builder/CodeDOM/CodeParameter.cs

@@ -57,7 +57,7 @@ public class CodeParameter : CodeTerminalWithKind<CodeParameterKind>, ICloneable
         type = value;
     }}
     public bool Optional {get;set;}
-    public string Description {get; set;}
+    public CodeDocumentation Documentation { get; set; } = new();
     public string DefaultValue {get; set;}
     public string SerializationName { get; set; }
     public object Clone()
@@ -67,10 +67,10 @@ public object Clone()
             Kind = Kind,
             Name = Name.Clone() as string,
             Type = Type?.Clone() as CodeTypeBase,
-            Description = Description?.Clone() as string,
             DefaultValue = DefaultValue?.Clone() as string,
             Parent = Parent,
             SerializationName = SerializationName?.Clone() as string,
+            Documentation = Documentation?.Clone() as CodeDocumentation,
         };
     }
 }

src/Kiota.Builder/CodeDOM/CodeProperty.cs

@@ -72,7 +72,7 @@ public CodeMethod SetterFromCurrentOrBaseType {
         type = value;
     }}
     public string DefaultValue {get;set;}
-    public string Description {get; set;}
+    public CodeDocumentation Documentation { get; set; } = new();
     public string SerializationName { get; set; }
     public string NamePrefix { get; set; }
     public bool IsNameEscaped { get => !string.IsNullOrEmpty(SerializationName); }

src/Kiota.Builder/CodeDOM/IDocumentedElement.cs

@@ -1,5 +1,4 @@
-namespace Kiota.Builder.CodeDOM {
-    public interface IDocumentedElement {
-        string Description {get; set;}
-    }
+namespace Kiota.Builder.CodeDOM;
+public interface IDocumentedElement {
+    CodeDocumentation Documentation {get; set;}
 }

src/Kiota.Builder/CodeDOM/ProprietableBlock.cs

@@ -28,7 +28,7 @@ public override string Name
             StartBlock.Name = name;
         }
     }
-    public string Description {get; set;}
+    public CodeDocumentation Documentation { get; set; } = new();
     public virtual IEnumerable<CodeProperty> AddProperty(params CodeProperty[] properties)
     {
         if(properties == null || properties.Any(x => x == null))