Document shift-left Win32 metadata annotation proposal - #2295
Document shift-left Win32 metadata annotation proposal#2295Jevan Saks (jevansaks) wants to merge 2 commits into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 78d1f91d-a6a2-4264-b049-36c8d156ac9d
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 78d1f91d-a6a2-4264-b049-36c8d156ac9d
Jon Wiswall (jonwis)
left a comment
Jon Wiswall (jonwis)
left a comment
There was a problem hiding this comment.
Looks great, a few comments/nits. Looking forward to the update!
| `_Outptr_result_maybenull_` use lowercase word segments. The Win32 additions | ||
| intentionally use PascalCase rather than copying that historical inconsistency. | ||
|
|
||
| `_Out_retval_` is not an SDK SAL macro and must not be described as one. For |
There was a problem hiding this comment.
This sounds like bot-chatter; what's it trying to tell me?
| _In_ DWORD count); | ||
| ``` | ||
|
|
||
| Do not place custom return annotations after the closing parenthesis. The earlier |
There was a problem hiding this comment.
Maybe have the bot run through all these and remove the "previously" or "this has changed since" kind of stuff. Tell it to only state the current net state goal, rather than the path taken. (I have an explicit note of that in my "writing as me" docs... don't include the path taken unless it's requested or necessary to explain a surprising change.)
|
|
||
| ```cpp | ||
| struct | ||
| DESCRIPTION { |
There was a problem hiding this comment.
This should have a sample attribute. Also, maybe see if clang-format supports formatting code-in-markdown-blocks?
| public metadata name while references continue to use the native typedef. | ||
|
|
||
| ```cpp | ||
| typedef BOOL (WINAPI *PUBLIC_CALLBACK)(DWORD value); |
| | P/Invoke module override | `_Win32_ImportLibrary_("name.dll")` | Function. Overrides import-library scan results. | | ||
| | `SupportedOSPlatform("windows...")` | One fixed `_Windows_SupportedOS_*_` macro from the menu below | Function, method, record, enum, or typedef. The macro expands to the canonical version string so authors cannot mistype it. | | ||
| | preserve exact return/result | `_Win32_PreserveResult_` | Function or method. Replaces both `CanReturnErrorsAsSuccess` and `CanReturnMultipleSuccessValues`; COM metadata uses standard `MethodImplAttributes.PreserveSig`. | | ||
| | `Agile` | `_Win32_Agile_` | Class/struct/interface declaration. | |
There was a problem hiding this comment.
Nit; agile usually goes on the class instead of the interface.
| | `RAIIFree("CloseX")` | `_Win32_RAIIFree_(CloseX)` | Producer function/method return or output parameter only. | | ||
| | `InvalidHandleValue(value)` | `_Win32_InvalidHandle_(value)` | Producer function/method return or output parameter only. Repeatable; signed decimal and hexadecimal C literals are accepted. | | ||
| | `NullNullTerminated` | Existing SAL `_NullNull_terminated_` | Return, parameter, field, or typedef. No custom annotation is required. | | ||
| | `Retained` | `_Win32_Retained_` | Parameter. | |
There was a problem hiding this comment.
More description? We had talked about a " is the end of the retained lifetime" annotation.
| | `RetVal` | MIDL `[retval]` or existing direction SAL plus `_Win32_Retval_` | Parameter. windows-rs parses `[retval]` from MIDL-generated header comments; C/C++-only declarations use the custom annotation. | | ||
| | `ComOutPtr` | `_COM_Outptr_` and standard SAL variants | Parameter. No new Win32 metadata annotation is required; shape-based inference is compatibility-only. | | ||
| | native constness | Native C/C++ `const` | Parameter or field. Const loss is a windows-rs RDL/winmd fidelity bug, not a header-annotation requirement. | | ||
| | scoped enum | guarded `enum class` | Emitted as `ScopedEnum`; normal branch retains the original ABI type. | |
There was a problem hiding this comment.
Would we want this to be the default for enums? In some world we upgrade all the enums to be enum class yyy so the naming works out.
| ```cpp | ||
| BOOL WINAPI OpenPrinterW( | ||
| _In_ LPWSTR name, | ||
| _Out_ |
There was a problem hiding this comment.
The thing I'm noticing here is that my eye skims over this attribute-per-line as if each were parameters.
Could we define this instead:
#define _Win32_RAIIFree(CloserFunc, ...) /* something using __VA_ARGS__ */
BOOL WINAPI OpenPrinterW(
_In_ LPWSTR name,
_Out_ _Win32_RAIIFree(ClosePrinter, 0, INVALID_HANDLE_VALUE) HANDLE* printer);| The unified pipeline must preserve fixes already present in direct windows-rs | ||
| generation: | ||
|
|
||
| 1. Read `__declspec(align(...))`/Clang alignment independently from packing. `CONTEXT` |
There was a problem hiding this comment.
Is this missing a sample showing use of CONTEXT ?
|
|
||
| ### AllJoyn - 545 initially missing P/Invokes | ||
|
|
||
| The `AllJoyn` partition defines `QCC_OS_GROUP_WINDOWS` and directly includes: |
There was a problem hiding this comment.
Let's start a thread internally on what we can do with this set of types.
2 participants
Summary
Key decisions captured
_Win32_prefix, such as_Win32_Retval_and_Win32_Retained_ProjectAsfrom the proposed vocabulary and consolidate exact-result behavior under_Win32_Preserve_result_HANDLEdeclarations and put lifecycle metadata only on producer returns and output parametersThis PR is documentation-only and is intended as the review package for the SDK and windows-rs design discussion.