Add annotations to describe what CRUD operations do to an entity set to Core

[JefWight]

Currently, Navigation Properties can have a Description and LongDescription annotation placed on them. This can be used to describe what entities in the collection mean, relative to the entity.

We would like the ability to also describe what it means to manipulate entities in a collection.

For example, a service that is used for managing email distribution lists may expose a /Users entity set containing a collection of users and a Distribution/BlockedSenders navigation property contains users whom are blocked from sending mail to that distribution list. A POST to the /Users collection is creating a new user, while a POST to the Distribution/BlockedSenders collection is not creating a new user, but instead blocking them from sending mail to that distribution list. In this case, the service may wish to annotate the BlockedSenders navigation property something like:

Description: A collection of users who are blocked from sending mail to this distribution list.
InsertDescription: Inserting a reference to a user into this collection will block any email they send to this distribution list from being forwarded to other members.
DeleteDescription: Deleting a reference to a user from this collection will restore their ability to send emails to this distribution list.

These annotations could be further used to provide richer comments on auto-generated client libraries and formatted documentation.

[ralfhandl]

Hi Jeff,

I'd like to continue this discussion on the odata-comment mailing list.

Thanks in advance!
--Ralf

[ralfhandl]

See https://lists.oasis-open.org/archives/odata-comment/201510/msg00005.html