Fix triple slash usage of inheritdoc.

[IEvangelist]

Description

Many of the container-based hosting integrations include an internal tags class, that stores the various container registry, image and tags. Since these members are internal the .NET Aspire API docs doesn't expose them in the rendered API docs. Nor are they available to IntelliSense.

For example, see RedisBuilderExtensions.AddRedis Method: Remarks.

To fix this, when we rely on <inheritdoc /> we must specify the path (XPath) to the desired value. Before my change:

After my change:

This will also fix the .NET Aspire API docs too, the next time we release.

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No
• Does the change require an update in our Aspire docs?
  • Yes
    • Is this introducing a breaking change?
      • Yes
        • Link to aspire-docs issue (please use this breaking-change template):
      • No
        • Link to aspire-docs issue (please use this doc-idea template):
  • No

Microsoft Reviewers: Open in CodeFlow

[eerhardt]

Can you fix these 2 as well?

aspire/src/Aspire.Hosting.Azure.CognitiveServices/AzureOpenAIDeployment.cs

Lines 37 to 51 in c0ff16d

	/// <summary>
	/// Gets the name of the SKU.
	/// </summary>
	/// <value>
	/// The default value is <inheritdoc cref="DefaultSkuName"/>.
	/// </value>
	public string SkuName { get; set; } = skuName ?? DefaultSkuName;
	/// <summary>
	/// Gets the capacity of the SKU.
	/// </summary>
	/// <value>
	/// The default value is <inheritdoc cref="DefaultSkuCapacity"/>.
	/// </value>
	public int SkuCapacity { get; set; } = skuCapacity ?? DefaultSkuCapacity;

[eerhardt]

There are 3 Azure ones that appear to be missed:

aspire/src/Aspire.Hosting.Azure.Storage/AzureStorageExtensions.cs

Line 85 in c0ff16d

/// This version of the package defaults to the <inheritdoc cref="StorageEmulatorContainerImageTags.Tag"/> tag of the <inheritdoc cref="StorageEmulatorContainerImageTags.Registry"/>/<inheritdoc cref="StorageEmulatorContainerImageTags.Image"/> container image.

aspire/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs

Line 109 in c0ff16d

/// This version of the package defaults to the <inheritdoc cref="CosmosDBEmulatorContainerImageTags.Tag"/> tag of the <inheritdoc cref="CosmosDBEmulatorContainerImageTags.Registry"/>/<inheritdoc cref="CosmosDBEmulatorContainerImageTags.Image"/> container image.

aspire/src/Aspire.Hosting.Azure.EventHubs/AzureEventHubsExtensions.cs

Line 81 in c0ff16d

/// This version of the package defaults to the <inheritdoc cref="EventHubsEmulatorContainerImageTags.Tag"/> tag of the <inheritdoc cref="EventHubsEmulatorContainerImageTags.Registry"/>/<inheritdoc cref="EventHubsEmulatorContainerImageTags.Image"/> container image.

(Although, that EventHubs one appears misplaced. It should be on the RunAsEmulator method.)

[eerhardt]

Can you make sure this works as expected? This is a 2-level reference:

aspire/src/Aspire.Hosting.RabbitMQ/RabbitMQContainerImageTags.cs

Lines 17 to 18 in c0ff16d

	/// <summary><inheritdoc cref="Tag"/>-management</summary>
	public const string ManagementTag = $"{Tag}-management";

aspire/src/Aspire.Hosting.RabbitMQ/RabbitMQBuilderExtensions.cs

Line 114 in c0ff16d

/// This version of the package defaults to the <inheritdoc cref="RabbitMQContainerImageTags.ManagementTag"/> tag of the <inheritdoc cref="RabbitMQContainerImageTags.Image"/> container image.

[sebastienros]

I recently created a PR that was fixing all these. Didn't we merge release/9.0 back to main? Pretty sure I updated everything to use in both the APIs and the tags.

[sebastienros]

Yes, that's it, check the release/9.0, it's fine there: https://github.com/dotnet/aspire/blob/release/9.0/src/Aspire.Hosting.Elasticsearch/ElasticsearchContainerImageTags.cs

[sebastienros]

release/9.0 is fine, but the PR didn't get merged back correctly apparently (conflicts got resolved using main) #6433

[IEvangelist]

There might be an issue with the .NET API docs. I'm investigating that and will report back.