[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: Proposing additional annotations - Remarks and Notes
|
Hi Jeff, Qualifiers allow applying the same term to the same target multiple times, so using them to distinguish different kinds of documentation is a valid application. “Title” also is one of my favorites. Given that it most likely would show up on user interfaces, I’d rather place it in the Display community vocabulary at
https://github.com/OData/vocabularies instead of the Core vocabulary at OASIS. If you agree, please go ahead and propose it there, the publication cycles of community vocabularies are somewhat shorter
J I’m looking forward to reading the documentation you create from your services! Thanks! --Ralf From: Jeff Wight [mailto:jeff.wight@microsoft.com] Hi Ralf, The desire for the Notes and Remarks fields were mostly raised from trying to document our services. We want to be able to have a fairly close match between the rich type of documentation possible in say an
API reference (think MSDN) and what we publish in our metadata. This allows us to both auto-generate API documentation based on the current service and auto-generate rich client libraries with the ability to turn all of that rich documentation into things
like intellisense comments. As a reference, if you were to look here: https://msdn.microsoft.com/en-us/library/system.threading.thread(v=vs.110).aspx We would love to have the flexibility to craft some version of that (with some custom mark-up for blocks) from metadata. Now if we look at the breakdown, this format effectively uses “Description” at the top
and “Remarks” at the bottom. As far as the Notes all go, some groups I’ve worked with had a desire to put footnotes under the “Properties” and “Methods” sections (different notes under each). I’m not sure that these notes are absolutely
necessary and couldn’t exist in the Remarks or in the property descriptions. I mostly brought these up as a brainstorming discussion. If there’s no uniform desire for supporting something like this, I’m sure we could come up with some custom service annotations
if need be. I do like your suggestion on Description => Summary, LongDescription => Remarks, and yes, “Title” would be useful for us too. I was unaware that “Qualifier” could be used in these means. Could we technically use “Qualifier=StructuralPropertyNotes” in our service or maybe “Qualifier=Examples” if we so chose to? If that’s the case,
I think that would absolutely satisfy our needs. Thanks, ~Jeff From: Handl, Ralf [mailto:ralf.handl@sap.com]
Hi Jeff, StructuralPropertyNotes, NavigationPropertyNotes, and OperationNotes: as we can apply a given term to any model element, it would probably suffice to just add one term Notes that can be applied to structural
properties, navigation properties, actions, and functions. Which would lead us to ·
Description ·
LongDescription ·
Remarks ·
Notes Is that the complete list, or would we find other specific terms if we take other documentation tools into account, maybe a Title for Swagger? What would be the semantic difference between Notes, Remarks, and LongDescription? Another way forward would be to say: ok, I need to differentiate between different flavors of LongDescription to satisfy the needs of my tool, so I define a set of qualifiers that give me that differentiation:
·
Core.Description becomes <summary> ·
Core.LongDescription becomes <remarks> ·
Core.LongDescription with Qualifier="Notes" becomes <notes>
·
And so on for all tool-specific documentation tags What do you think? Thanks in advance! PS: I write this with my “TC member” hat on, so this is not an official statement of the TC From:
odata-comment@lists.oasis-open.org [mailto:odata-comment@lists.oasis-open.org]
On Behalf Of Jeff Wight Hi, While going through exercises to better document our OData service, we came up with a collection of annotations we think we’d need in order to specify the rich content we’d like to express. Here is a summary of some of the needs that I believe will be useful to any OData service: Capabilities: ·
SelectRestrictions – Similar to Filter, Sort, and Expand Restrictions, we need the ability to specify if a collection supports $select, and which properties are non-selectable. ·
UpsertSupported – Fairly self-explanatory, a tag to indicate whether a given entity set supports Upsert. We’d also like to considering how to differentiate PATCH vs PUT flavors of Upsert. Core: ·
CRUD Descriptions – We already have the ability to identify which CRUD operations are supported on an entity set, using Insert, Update, and Delete Restrictions, but we’d like to be able to provide specific comments about
these actions. For example, a service that manages distribution lists may allow you POST to the /Users collection, meaning you are creating a user, however if you POST to the Distribution/BlockedSenders collection, this means you are blacklisting that user
from being able to send mail to that group. While one could imply this using the description of the entity set itself, it would allow us to be a bit more descriptive / contextual / clear here. ·
Operation ErrorCodes – Similar to how C# summary comments allow you to specify any <exception>s that a method may potentially throw, we would like to be able to specify the ErrorCodes that a given Operation may return,
along with a blurb on what that error code means / how to resolve it. ·
Operation Prerequisites – Any special conditions that must be met before a caller should expect they can call an operation. For example, an email service may expose a Send operation on an Email entity, but in order to
invoke it, the email must have at least one of To:, CC:, or BCC: set. In addition to the above, we have a need to expose the following as well, though I’m not sure they would be as generally useful to any OData service, but including here for discussion: ·
Entity Remarks – This is slightly different than Description or LongDescription, but similar to the <remarks> tag in c# summary documentation. ·
OAuth Scopes – Since our OData service support OAuth2, we’d like to be able to describe which OAuth scopes are required for interacting with an entity. For example, an Email requires Mail.Read while an Event requires Calendar.Read.
It would also be nice to be able to specify that UPDATE and DELETE require the .ReadWrite permission. ·
Generic Schema Notes – These would be generic notes / footnotes on an entity that would apply to StructuralProperties, NavigationProperties, and Operations. I would imagine this as StructuralPropertyNotes, NavigationPropertyNotes,
and OperationNotes Thoughts? Thanks, |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]