How to add documentation on resource identifiers or properties?

[Jérôme Dauge]

Hello,

I cannot find a proper way to define documentation for a resource identifiers or properties.

From the smithy-examples repository, how do you recommend to define documentation for the City resource identifiers or properties?

resource City {
    identifiers: { cityId: CityId }
    properties: { coordinates: CityCoordinates }
    read: GetCity
    list: ListCities
    resources: [
        Forecast
    ]
}

Both the @documentation trait and /// doesn't work inside the definition of the resource (either in identifiers or properties). Here are two invalid examples:

resource City {
    identifiers: { 
    	@documentation("City ID")
    	cityId: CityId 
	}
    properties: { coordinates: CityCoordinates }
    read: GetCity
    list: ListCities
    resources: [
        Forecast
    ]
}

resource City {
    identifiers: { 
    	/// City ID
    	cityId: CityId 
	}
    properties: { coordinates: CityCoordinates }
    read: GetCity
    list: ListCities
    resources: [
        Forecast
    ]
}

It is possible to document when using the elision syntax. However, this leads to a lot of duplication, so it is more convenient to document it once at the resource level.

[Michael Dowling]

Resource properties and identifiers aren’t members so they can’t bear traits. They point to root level shapes. You can document those root level shapes. This turns out to be a very good thing. It encourages shape reuse and consistency across resource operations because members of operation inputs and outputs have to target the same shapes as the resource. It also makes automatic identifier and resource property binding work.