Documentation on Metadata Semantics

[marler8997]

The metadata leverages semantics from the Clr along with custom attributes to represent the win32 API. I'd like to see documentation that describes what the metadata contains and how it translates to API semantics. This would provide an overall picture of what's contained within the metadata which helps both metadata maintainers and projection developers know what's supported and how to properly translate the API to their language of choice.

In this documentation I'd expect to see explanations on what all the custom attributes mean, and explanations of how to translate Clr semantics to native API semantics, things like this:

• native unions are represented as Clr structs with an explicit layout, where all fields contain an offset of 0
• typedefs are represented as Clr structs with a single field, where the NativeTypedef attribute is applied to the struct. The type being defined is given by the name of the struct, and the type it is being defined as is the type of the one struct field. The new type being defined inherits the RAIIFree attribute if it exists on the base type.
• The [AlsoUsableFor("SomeType")] attribute can be applied to a type and indicates that type is "implicitly convertible" to the given "SomeType". Note that the type being defined does not inherit the RAIIFree attribute from type given in the AlsoUsableFor attribute.

This is just a small sample of what I'd expect to be in the documentation. Since this metadata is in its early stages I would expect the documentation to be versioned alongside with the implementation so they can change at the same pace. If this were maintained as a single document inside the metadata repository, it would provide a nice easy way for projection authors to look at what has changed since the last version.

[mikebattista]

Yes we do need this. #97 tracks the need for documentation like this. I've linked the two to capture the feedback and will close this one.

@marler8997 are you working on a projection?

[marler8997]

@mikebattista, yes, I've developed and am maintaining a projection to the Zig programming language. However, it's a bit different than a normal projection because I'm just generating the entire API rather than providing build infrastructure to generate pieces of it on the fly.

The project that generates the code is here: https://github.com/marlersoft/zigwin32gen
When I release a new version I push the generated code here: https://github.com/marlersoft/zigwin32

Also note that rather than writing a winmd parser in Zig, I decided to leverage .NET reflection to convert the winmd file to JSON first. This way I can write the Zig projection in Zig and consume the JSON instead of writing a winmd parser in Zig. I've also found the JSON projection is nice for inspecting/grepping through the metadata as I can use alot more tools to work with it than the winmd format. The project that "projects" the winmd format to JSON is here:

https://github.com/marlersoft/win32jsongen

And the generated JSON files are here: https://github.com/marlersoft/win32json

[mikebattista]

Awesome! I've linked to it in our projections list in this repo.

Also converting the winmd to JSON to make it more accessible in your language is great too. #144 requested other formats and we were hoping others could provide such conversions based on the canonical winmd. I'll mention your JSON format in the projection implementer guide when discussing how to parse the winmd and alternative formats.

Please do let us know other challenges you hit building and maintaining your projection. Feel free to add comments to the open issue (#97) tracking the documentation.

Appreciate your patience while we stabilize the metadata at this early stage.