Consider including machine readable docs for published APIs so that languages can generate code comments

[kennykerr]

No description provided.

[kennykerr]

FYI @asklar has been experimenting with doing this for WinRT APIs.

[AArnott]

The C# projection uses this tool to scrape docs into YAML for inclusion as xml doc comments in the C#-produced APIs.
It's intended to be shareable. We could move that tool into this repo if that's helpful.

[asklar]

I think we will want to use the same approach we'll use for cswinrt where we'd use roslyn to turn XML comments into a custom attribute in the winmd, that can be read by any number of tools.

[AArnott]

The docs are 50+ MBs, @asklar. I'd rather the metadata dll not be so huge. In fact, I hear that assemblies have a max size (or 10MB?) for how much space can be spent on strings, so it may be technically impossible to put all the docs in the assembly as custom attributes.
I think the docs should remain outside the metadata dll.

[AArnott]

Keeping the docs separate from the dll also allows for the possibility of localization where the projection produces docs in the author or project's preferred language rather than always English.

[asklar]

FWIW localization can be baked into the custom property, just like classic COM did helpstringdll / helpstringcontext (an ID and a DLL)