Documenting use of [contract] midl attribute for API versioning#406
Documenting use of [contract] midl attribute for API versioning#406ChrisGuzak wants to merge 1 commit intoMicrosoftDocs:docsfrom
Conversation
|
@ChrisGuzak : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
prmerger-automator
bot
added
Change sent to author
uwp/svc
winrt-reference/subsvc
labels
|
Learn Build status updates of commit e8239c5: ✅ Validation status: passed
For more details, please refer to the build report. |
| The `contract` attribute is used to version APIs; for example when creating a | ||
| Software Development Kit where strong contracts are needed. It indicates the API contract | ||
| name and two decimal values; `[contract(ContractName, LeftNumber.RightNumber)]` | ||
| with `RightNumber` being optional. |
There was a problem hiding this comment.
Did you want to call these "Major" and "Minor" instead of left/right here, since you mention that's what they mean below? With this documentation there should probably be an "examples of use" conceptual page...
There was a problem hiding this comment.
I think the paragraph is too much "inside baseball". Maybe
The
contractattribute can be used to specify which version of an API contract the attributed type belongs to. The attribute takes the form[contract(ContractName, MajorVersion.MinorVersion)]. The MIDL compiler enforces some rules on contracts. Note that this list is not exhaustive.
- The MajorVersion.MinorVersion may not be greater than the major and minor version specified in the
[contractversion]attribute of the referencedapicontract.- A member of a runtimeclass may not have a lower contract number than the class itself.
- A member of a runtimeclass may not refer to types from contracts lower than that of the member itself. (A member without an explicit contract is assumed to belong to the same contract as the containing runtimeclass.)
| It appears before the item to which it applies and can apply to several artifacts | ||
| by using braces (`{}`) to group those parts of the API. | ||
|
|
||
| Designs that don't need versioning should not use this attribute, or should keep the |
There was a problem hiding this comment.
I think this is already covered in the opening paragraphs of this page.
If you're a component developer and/or a library author, then you may wish to use these attributes to ensure that your components remain binary-stable from one version to the next.
If you're an application developer, then in general you won't need to use these attributes because you'll recompile your application after revisioning your types.
| The `contract` attribute is used to version APIs; for example when creating a | ||
| Software Development Kit where strong contracts are needed. It indicates the API contract | ||
| name and two decimal values; `[contract(ContractName, LeftNumber.RightNumber)]` | ||
| with `RightNumber` being optional. |
There was a problem hiding this comment.
I think the paragraph is too much "inside baseball". Maybe
The
contractattribute can be used to specify which version of an API contract the attributed type belongs to. The attribute takes the form[contract(ContractName, MajorVersion.MinorVersion)]. The MIDL compiler enforces some rules on contracts. Note that this list is not exhaustive.
- The MajorVersion.MinorVersion may not be greater than the major and minor version specified in the
[contractversion]attribute of the referencedapicontract.- A member of a runtimeclass may not have a lower contract number than the class itself.
- A member of a runtimeclass may not refer to types from contracts lower than that of the member itself. (A member without an explicit contract is assumed to belong to the same contract as the containing runtimeclass.)
|
Thanks for this PR, it looks good! Once the feedback is actioned, I'll be ready to Merge. :) |
4 participants
This attribute is used for API versioning and is not specific to Windows SDK use. Document this fact.