Metrictype -- appallingly incomplete documentation

[rm-minus-r-star]

Type of issue

Typo

Description

None of the arguments are explained. No example usage. I'm trying to dig down from https://learn.microsoft.com/en-us/python/api/azure-mgmt-consumption/azure.mgmt.consumption.operations.usagedetailsoperations?view=azure-python to work out how to get the parameters I need, Metrictype appears to be the only option, but the drill down to this page is completely useless.

Page URL

https://learn.microsoft.com/en-us/python/api/azure-mgmt-consumption/azure.mgmt.consumption.models.metrictype?view=azure-python

Content source URL

https://github.com/MicrosoftDocs/azure-docs-sdk-python/blob/main/docs-ref-autogen/azure-mgmt-consumption/azure.mgmt.consumption.models.Metrictype.yml

Document Version Independent Id

a167a816-7f9b-ff42-c4b3-d3c1e233087b

Article author

@lmazuel

Metadata

• ID: 89187bc8-1b55-1ae1-fc17-616f2ba00336
• Service: consumption

[xiangyan99]

Thanks for the feedback, we’ll investigate asap.

[kristapratico]

FYI @rohit-ganguly

Looks like enum descriptions don't get included in the MS Learn docs: https://learn.microsoft.com/en-us/python/api/azure-mgmt-consumption/azure.mgmt.consumption.models.metrictype?view=azure-python

Github.io docs do include the generated descriptions: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-mgmt-consumption/10.0.0/azure.mgmt.consumption.models.html#azure.mgmt.consumption.models.Metrictype

[nickwalkmsft]

Including enum descriptions is a feature request I can get tracked on the Learn docs generation side, but it doesn't sound like that's the actual feedback here, and while that would be an improvement overall, in this particular case the descriptions don't shed any light anyway.

Does >None of the arguments are explained refer to this?

That is indeed a weird look. At first I had no idea why those args were there, then I recognized them as the arguments you can give the Enum constructor when you're defining an Enum functional-style. I'm not sure why the docs generation process ends up putting those there or if they're present for all Python enums on Learn, but I do see that on the Github.io docs, some enums them and some don't, and I'm not sure why. For example, the doc you linked for this particular enum doesn't have them, but for these enums in azure.mgmt.wev.v2021_01_15 they do.

Does anyone have any insight here?

[lmazuel]

@nickwalkmsft enum value doc is infered from the original spec (Swagger or TypeSpec). So it all come back to the spec author. For instance for the link you share where it's not there:

https://github.com/Azure/azure-rest-api-specs/blob/981a44d26823fc6056b30fc1008c23d25beb5aff/specification/web/resource-manager/Microsoft.Web/stable/2018-02-01/Provider.json#L28-L37

And for the doc where they are here:

https://github.com/Azure/azure-rest-api-specs/blob/981a44d26823fc6056b30fc1008c23d25beb5aff/specification/consumption/resource-manager/Microsoft.Consumption/stable/2019-05-01/consumption.json#L3250-L3273

So I agree with @kristapratico assessment that the feedback here is the lack doc for the enum. But it does assume indeed that the initial spec author did the right thing. And in his particular case, it happens it was available and it got lost in processing.

[msyyc]

In source SDK code, we add the description for enum value in annotation:

azure-sdk-for-python/sdk/consumption/azure-mgmt-consumption/azure/mgmt/consumption/models/_consumption_management_client_enums.py

Lines 107 to 115 in 0b0345a

	class Metrictype(str, Enum, metaclass=CaseInsensitiveEnumMeta):
	"""Metrictype."""
	#: Actual cost data.
	ACTUAL_COST_METRIC_TYPE = "actualcost"
	#: Amortized cost data.
	AMORTIZED_COST_METRIC_TYPE = "amortizedcost"
	#: Usage data.
	USAGE_METRIC_TYPE = "usage"

. While the doc yaml doesn't contain those annotation https://github.com/MicrosoftDocs/azure-docs-sdk-python/blob/main/docs-ref-autogen/azure-mgmt-consumption/azure.mgmt.consumption.models.Metrictype.yml. I think we may need optimize the process to extract doc from source SDK code.