search

microsoft / CsWin32

A source generator to add a user-defined set of Win32 P/Invoke methods and supporting types to a C# project.
MIT License
2.06k stars 87 forks source link

Leverage DocumentationAttribute #931

Closed AArnott closed 1 year ago

AArnott commented 1 year ago

win32metadata recently added [Documentation(url)] attributes to APIs.

CsWin32 already gets doc URLs from the docs nuget package (along with the docs themselves). If these attributes might describe more doc URLs than we're getting from the docs nuget package, we should probably switch where we get the doc URLs from.

@mikebattista, can you comment as to whether the documentation attribute may be a better source than the docs nuget package for doc URLs?

mikebattista commented 1 year ago

You'll get the same API coverage and URLs whether you consume the Win32Docs package or the attribute. The attribute remap file used to populate the metadata is actually generated as an artifact during the Win32Docs package build.

The attribute is for simple scenarios where you just need a URL and don't want or can't load the Win32Docs package. The Rust projection for example needs the attribute in the metadata if they want to add the URLs to the Rust docs. They don't/can't consume the Win32Docs package.