feat: Improved xml docs for methods and models.

src/libs/Directory.Build.props

@@ -39,7 +39,7 @@
   </ItemGroup>
 
   <PropertyGroup Label="Versioning">
-    <Version>0.10.3</Version>
+    <Version>0.10.4</Version>
     <MinVerMinimumMajorMinor>0.1</MinVerMinimumMajorMinor>
     <MinVerTagPrefix>v</MinVerTagPrefix>
     <MinVerDefaultPreReleaseIdentifiers>dev</MinVerDefaultPreReleaseIdentifiers>

src/libs/OpenApiGenerator.Core/Extensions/OpenApiExtensions.cs

@@ -114,14 +114,46 @@ public static string GetSummary(this OpenApiSchema schema)
 
         // Remove any XML tags from the description
         var summary = schema.Description?.ClearForXml() ?? string.Empty;
-        if (schema.Default != null)
+        var @default = schema.Default.GetString()?.ClearForXml();
+        if (!string.IsNullOrWhiteSpace(@default))
         {
-            summary += $"\n<br/>Default Value: {schema.Default.GetString()?.ClearForXml()}";
+            if (!string.IsNullOrWhiteSpace(summary))
+            {
+                summary += "\n";
+            }
+
+            summary += $"Default Value: {@default}";
         }
 
-        if (schema.Example != null)
+        var example = schema.Example.GetString()?.ClearForXml();
+        if (!string.IsNullOrWhiteSpace(example))
         {
-            summary += $"\n<br/>Example: {schema.Example.GetString()?.ClearForXml()}";
+            if (!string.IsNullOrWhiteSpace(summary))
+            {
+                summary += "\n";
+            }
+
+            summary += $"Example: {example}";
+        }
+
+        return summary;
+    }
+
+    public static string GetXmlDocumentationSummary(this OpenApiOperation operation)
+    {
+        operation = operation ?? throw new ArgumentNullException(nameof(operation));
+
+        // Remove any XML tags from the description
+        var summary = operation.Summary?.ClearForXml() ?? string.Empty;
+        var description = operation.Description?.ClearForXml();
+        if (!string.IsNullOrWhiteSpace(description))
+        {
+            if (!string.IsNullOrWhiteSpace(summary))
+            {
+                summary += "\n";
+            }
+
+            summary += $"{description}";
         }
 
         return summary;

src/libs/OpenApiGenerator.Core/Extensions/StringExtensions.cs

@@ -149,7 +149,7 @@ public static string ToXmlDocumentationSummary(
 
         var spaces = new string(' ', level);
         var value = string.Join("\n", lines
-            .Select(line => $"{spaces}/// {line}"));
+            .Select((line, i) => $"{spaces}/// {line}{(i != lines.Length - 1 ? "<br/>" : string.Empty)}"));
 
         return addSummary
             ? $@"/// <summary>

src/libs/OpenApiGenerator.Core/Generation/Sources.Methods.cs

@@ -70,9 +70,7 @@ public static string GenerateMethod(
             : string.Empty;
 
         return $@" 
-        /// <summary>
-        /// {endPoint.Summary}
-        /// </summary>
+        {endPoint.Summary.ToXmlDocumentationSummary(level: 8)}
 {endPoint.Properties.Where(x => x.ParameterLocation != null).Select(x => $@"
         /// <param name=""{x.ParameterName}""></param>").Inject()}
 {(string.IsNullOrWhiteSpace(endPoint.RequestType.CSharpType) ? " " : @" 
@@ -165,9 +163,7 @@ public static string GenerateExtensionMethod(
             : string.Empty;
 
         return $@"
-        /// <summary>
-        /// {endPoint.Summary}
-        /// </summary>
+        {endPoint.Summary.ToXmlDocumentationSummary(level: 8)}
 {endPoint.Properties.Select(x => $@"
         /// <param name=""{x.ParameterName}""></param>").Inject()}
         /// <param name=""cancellationToken"">The token to cancel the operation with</param>

src/libs/OpenApiGenerator.Core/Models/EndPoint.cs

@@ -196,7 +196,7 @@ public static EndPoint FromSchema(
             JsonSerializerContext: settings.JsonSerializerContext,
             GenerateJsonSerializerContextTypes: settings.GenerateJsonSerializerContextTypes,
             HttpMethod: operation.Key,
-            Summary: operation.Value.Summary?.Replace("\n", string.Empty) ?? string.Empty,
+            Summary: operation.Value.GetXmlDocumentationSummary(),
             BaseUrlSummary: string.Empty,
             RequestType: requestType ?? TypeData.Default,
             ResponseType: responseType ?? TypeData.Default,

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.Api.g.verified.cs

@@ -5,8 +5,8 @@
 namespace G
 {
     /// <summary>
-    /// GitHub's v3 REST API.
-    /// If no httpClient is provided, a new one will be created.
+    /// GitHub's v3 REST API.<br/>
+    /// If no httpClient is provided, a new one will be created.<br/>
     /// If no baseUri is provided, the default baseUri from OpenAPI spec will be used.
     /// </summary>
     public sealed partial class Api : global::System.IDisposable

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsCancelImport.g.verified.cs

@@ -7,7 +7,9 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Cancel an import
+        /// Cancel an import<br/>
+        /// Stop an import for a repository.<br/>
+        /// **Warning:** Due to very low levels of usage and available alternatives, this endpoint is deprecated and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the [changelog](https://gh.io/source-imports-api-deprecation).
         /// </summary>
         /// <param name="owner"></param>
         /// <param name="repo"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsDeleteArchiveForAuthenticatedUser.g.verified.cs

@@ -7,7 +7,8 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Delete a user migration archive
+        /// Delete a user migration archive<br/>
+        /// Deletes a previous migration archive. Downloadable migration archives are automatically deleted after seven days. Migration metadata, which is returned in the [List user migrations](https://docs.github.com/rest/migrations/users#list-user-migrations) and [Get a user migration status](https://docs.github.com/rest/migrations/users#get-a-user-migration-status) endpoints, will continue to be available even after an archive is deleted.
         /// </summary>
         /// <param name="migrationId"></param>
         /// <param name="cancellationToken">The token to cancel the operation with</param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsDeleteArchiveForOrg.g.verified.cs

@@ -7,7 +7,8 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Delete an organization migration archive
+        /// Delete an organization migration archive<br/>
+        /// Deletes a previous migration archive. Migration archives are automatically deleted after seven days.
         /// </summary>
         /// <param name="org"></param>
         /// <param name="migrationId"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsDownloadArchiveForOrg.g.verified.cs

@@ -7,7 +7,8 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Download an organization migration archive
+        /// Download an organization migration archive<br/>
+        /// Fetches the URL to a migration archive.
         /// </summary>
         /// <param name="org"></param>
         /// <param name="migrationId"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsGetArchiveForAuthenticatedUser.g.verified.cs

@@ -7,7 +7,26 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Download a user migration archive
+        /// Download a user migration archive<br/>
+        /// Fetches the URL to download the migration archive as a `tar.gz` file. Depending on the resources your repository uses, the migration archive can contain JSON files with data for these objects:<br/>
+        /// *   attachments<br/>
+        /// *   bases<br/>
+        /// *   commit\_comments<br/>
+        /// *   issue\_comments<br/>
+        /// *   issue\_events<br/>
+        /// *   issues<br/>
+        /// *   milestones<br/>
+        /// *   organizations<br/>
+        /// *   projects<br/>
+        /// *   protected\_branches<br/>
+        /// *   pull\_request\_reviews<br/>
+        /// *   pull\_requests<br/>
+        /// *   releases<br/>
+        /// *   repositories<br/>
+        /// *   review\_comments<br/>
+        /// *   schema<br/>
+        /// *   users<br/>
+        /// The archive will also contain an `attachments` directory that includes all attachment files uploaded to GitHub.com and a `repositories` directory that contains the repository's Git data.
         /// </summary>
         /// <param name="migrationId"></param>
         /// <param name="cancellationToken">The token to cancel the operation with</param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsGetCommitAuthors.g.verified.cs

@@ -7,7 +7,10 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Get commit authors
+        /// Get commit authors<br/>
+        /// Each type of source control system represents authors in a different way. For example, a Git commit author has a display name and an email address, but a Subversion commit author just has a username. The GitHub Importer will make the author information valid, but the author might not be correct. For example, it will change the bare Subversion username `hubot` into something like `hubot &lt;hubot@12341234-abab-fefe-8787-fedcba987654&gt;`.<br/>
+        /// This endpoint and the [Map a commit author](https://docs.github.com/rest/migrations/source-imports#map-a-commit-author) endpoint allow you to provide correct Git author information.<br/>
+        /// **Warning:** Due to very low levels of usage and available alternatives, this endpoint is deprecated and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the [changelog](https://gh.io/source-imports-api-deprecation).
         /// </summary>
         /// <param name="owner"></param>
         /// <param name="repo"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsGetImportStatus.g.verified.cs

@@ -7,7 +7,31 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Get an import status
+        /// Get an import status<br/>
+        /// View the progress of an import.<br/>
+        /// **Warning:** Due to very low levels of usage and available alternatives, this endpoint is deprecated and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the [changelog](https://gh.io/source-imports-api-deprecation).<br/>
+        /// **Import status**<br/>
+        /// This section includes details about the possible values of the `status` field of the Import Progress response.<br/>
+        /// An import that does not have errors will progress through these steps:<br/>
+        /// *   `detecting` - the "detection" step of the import is in progress because the request did not include a `vcs` parameter. The import is identifying the type of source control present at the URL.<br/>
+        /// *   `importing` - the "raw" step of the import is in progress. This is where commit data is fetched from the original repository. The import progress response will include `commit_count` (the total number of raw commits that will be imported) and `percent` (0 - 100, the current progress through the import).<br/>
+        /// *   `mapping` - the "rewrite" step of the import is in progress. This is where SVN branches are converted to Git branches, and where author updates are applied. The import progress response does not include progress information.<br/>
+        /// *   `pushing` - the "push" step of the import is in progress. This is where the importer updates the repository on GitHub. The import progress response will include `push_percent`, which is the percent value reported by `git push` when it is "Writing objects".<br/>
+        /// *   `complete` - the import is complete, and the repository is ready on GitHub.<br/>
+        /// If there are problems, you will see one of these in the `status` field:<br/>
+        /// *   `auth_failed` - the import requires authentication in order to connect to the original repository. To update authentication for the import, please see the [Update an import](https://docs.github.com/rest/migrations/source-imports#update-an-import) section.<br/>
+        /// *   `error` - the import encountered an error. The import progress response will include the `failed_step` and an error message. Contact [GitHub Support](https://support.github.com/contact?tags=dotcom-rest-api) for more information.<br/>
+        /// *   `detection_needs_auth` - the importer requires authentication for the originating repository to continue detection. To update authentication for the import, please see the [Update an import](https://docs.github.com/rest/migrations/source-imports#update-an-import) section.<br/>
+        /// *   `detection_found_nothing` - the importer didn't recognize any source control at the URL. To resolve, [Cancel the import](https://docs.github.com/rest/migrations/source-imports#cancel-an-import) and [retry](https://docs.github.com/rest/migrations/source-imports#start-an-import) with the correct URL.<br/>
+        /// *   `detection_found_multiple` - the importer found several projects or repositories at the provided URL. When this is the case, the Import Progress response will also include a `project_choices` field with the possible project choices as values. To update project choice, please see the [Update an import](https://docs.github.com/rest/migrations/source-imports#update-an-import) section.<br/>
+        /// **The project_choices field**<br/>
+        /// When multiple projects are found at the provided URL, the response hash will include a `project_choices` field, the value of which is an array of hashes each representing a project choice. The exact key/value pairs of the project hashes will differ depending on the version control type.<br/>
+        /// **Git LFS related fields**<br/>
+        /// This section includes details about Git LFS related fields that may be present in the Import Progress response.<br/>
+        /// *   `use_lfs` - describes whether the import has been opted in or out of using Git LFS. The value can be `opt_in`, `opt_out`, or `undecided` if no action has been taken.<br/>
+        /// *   `has_large_files` - the boolean value describing whether files larger than 100MB were found during the `importing` step.<br/>
+        /// *   `large_files_size` - the total size in gigabytes of files larger than 100MB found in the originating repository.<br/>
+        /// *   `large_files_count` - the total number of files larger than 100MB found in the originating repository. To see a list of these files, make a "Get Large Files" request.
         /// </summary>
         /// <param name="owner"></param>
         /// <param name="repo"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsGetLargeFiles.g.verified.cs

@@ -7,7 +7,9 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Get large files
+        /// Get large files<br/>
+        /// List files larger than 100MB found during the import<br/>
+        /// **Warning:** Due to very low levels of usage and available alternatives, this endpoint is deprecated and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the [changelog](https://gh.io/source-imports-api-deprecation).
         /// </summary>
         /// <param name="owner"></param>
         /// <param name="repo"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsGetStatusForAuthenticatedUser.g.verified.cs

@@ -8,7 +8,13 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Get a user migration status
+        /// Get a user migration status<br/>
+        /// Fetches a single user migration. The response includes the `state` of the migration, which can be one of the following values:<br/>
+        /// *   `pending` - the migration hasn't started yet.<br/>
+        /// *   `exporting` - the migration is in progress.<br/>
+        /// *   `exported` - the migration finished successfully.<br/>
+        /// *   `failed` - the migration failed.<br/>
+        /// Once the migration has been `exported` you can [download the migration archive](https://docs.github.com/rest/migrations/users#download-a-user-migration-archive).
         /// </summary>
         /// <param name="migrationId"></param>
         /// <param name="exclude"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsGetStatusForOrg.g.verified.cs

@@ -8,7 +8,13 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Get an organization migration status
+        /// Get an organization migration status<br/>
+        /// Fetches the status of a migration.<br/>
+        /// The `state` of a migration can be one of the following values:<br/>
+        /// *   `pending`, which means the migration hasn't started yet.<br/>
+        /// *   `exporting`, which means the migration is in progress.<br/>
+        /// *   `exported`, which means the migration finished successfully.<br/>
+        /// *   `failed`, which means the migration failed.
         /// </summary>
         /// <param name="org"></param>
         /// <param name="migrationId"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsListForAuthenticatedUser.g.verified.cs

@@ -7,7 +7,8 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// List user migrations
+        /// List user migrations<br/>
+        /// Lists all migrations a user has started.
         /// </summary>
         /// <param name="perPage"></param>
         /// <param name="page"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsListForOrg.g.verified.cs

@@ -8,7 +8,9 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// List organization migrations
+        /// List organization migrations<br/>
+        /// Lists the most recent migrations, including both exports (which can be started through the REST API) and imports (which cannot be started using the REST API).<br/>
+        /// A list of `repositories` is only returned for export migrations.
         /// </summary>
         /// <param name="org"></param>
         /// <param name="perPage"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsListReposForAuthenticatedUser.g.verified.cs

@@ -7,7 +7,8 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// List repositories for a user migration
+        /// List repositories for a user migration<br/>
+        /// Lists all the repositories for this user migration.
         /// </summary>
         /// <param name="migrationId"></param>
         /// <param name="perPage"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsListReposForOrg.g.verified.cs

@@ -7,7 +7,8 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// List repositories in an organization migration
+        /// List repositories in an organization migration<br/>
+        /// List all the repositories for this organization migration.
         /// </summary>
         /// <param name="org"></param>
         /// <param name="migrationId"></param>

src/tests/OpenApiGenerator.SnapshotTests/Snapshots/Filtering/NewtonsoftJson/_#G.MigrationsClient.MigrationsMapCommitAuthor.g.verified.cs

@@ -7,7 +7,10 @@ namespace G
     public partial class MigrationsClient
     {
         /// <summary>
-        /// Map a commit author
+        /// Map a commit author<br/>
+        /// Update an author's identity for the import. Your application can continue updating authors any time before you push<br/>
+        /// new commits to the repository.<br/>
+        /// **Warning:** Due to very low levels of usage and available alternatives, this endpoint is deprecated and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the [changelog](https://gh.io/source-imports-api-deprecation).
         /// </summary>
         /// <param name="owner"></param>
         /// <param name="repo"></param>
@@ -46,7 +49,10 @@ public partial class MigrationsClient
         }
 
         /// <summary>
-        /// Map a commit author
+        /// Map a commit author<br/>
+        /// Update an author's identity for the import. Your application can continue updating authors any time before you push<br/>
+        /// new commits to the repository.<br/>
+        /// **Warning:** Due to very low levels of usage and available alternatives, this endpoint is deprecated and will no longer be available from 00:00 UTC on April 12, 2024. For more details and alternatives, see the [changelog](https://gh.io/source-imports-api-deprecation).
         /// </summary>
         /// <param name="owner"></param>
         /// <param name="repo"></param>