ChannelDetails docs are misleading

[owenpearson]

The ChannelDetails type is used for both the channel status REST API and for lifecycle events sent with the channel.lifecycle reactor source. In the former case the region and isGlobalMaster fields are always absent and the ChannelDetails.status and ChannelDetails.status.occupancy fields are always present, however this is not true for the latter case. It is not possible from the docs to infer this so one might assume when using the REST API that ChannelDetails.status might not be returned (as has happened here #1455).

We could avoid this confusion by doing either of the following:

1. Document two separate types for each of these cases - these types could still share the underlying Occupancy type.
2. Add a paragraph to the docs for ChannelDetails to explain when each optional field will be present.

I personally think 1 would be much better but 2 would obviously require less work.

┆Issue is synchronized with this Jira Task by Unito