Constants and enums should provide xml documentation

[netcorefan1]

Is your feature request related to a problem? Please describe. More than a problem is an annoyance. I noticed that constants and enums does not provide any xml documentation and this forces me to manually write them. An example is OBJECT_IDENTIFIER enum and EVENT_SYSTEM_FOREGROUND constant.

Describe the solution you'd like Generate xml documentation for this types. Being forced to open the browser to see what a particular value does is not convenient.

Describe alternatives you've considered Showing the whole table from the Microsoft web site would be perfectly acceptable rather than mapping each value to its own description.

[AArnott]

Not all constants have documented summaries. (And I think all enums are constants to win32).

I'd love to get docs more thoroughly applied to constants, but it can be tricky because the docs' representation of summaries for them varies a lot (far more than it varies for functions), and we get the docs by scraping the docs web site (or rather, the repo behind it). In any case, an improvement here would mean a change to the win32metadata repo rather than CsWin32. CsWin32 is quite happy to emit docs whenever the metadata or docs package provide it.

[netcorefan1]

I understand what you mean. Pheraps, when the format/layout of the documentation is not supported by the scraper, an option could be to allow the user to upload the snippets with the required documentation in some section of the repo. This means that it will not be an automated process anymore and new constants will lack docs unless someone upload the updates. However, a couple of new constants without documentation is still better than no documentation at all.

[AArnott]

Are you saying that you want xml docs on the generated APIs enough that you'd be willing to fetch them from the online documentation and check them into your repo manually? If so, we may be able to add such support for that in CsWin32. But doing it in a way where you could check it into this win32metadata repo instead would allow all other generators and users to benefit as well.

[netcorefan1]

Well, I means more something like pull requests doable directly from within VS in order to open the feature to all the users, not only the ones with a cloned CsWin32 repo. Something like this showing in intellisense: This member lacks xml doc. Click here to create and upload documentation..

OnClick should open a generated class with all fields prepopulated with sample xml code. A Submit button should be available which will allow the user to submit (preferibly without a GH account) to a server.

Not sure on how could be implemented the UI interaction side. Would be very easy with a VSIX extension, but without I have no idea (may be a source generator or some script in NuGet?). Given that CsWin32 is part of Microsoft, the best would be a little change to the Ide that, based on the presence of a CsWin32 package, will automatically take care of the submission.

[AArnott]

That sounds great, but it's not going to happen. I was thinking something more along the lines of you submitting the missing docs in a PR to the win32metadata repo so that a future release of the metadata package, CsWin32 (and all other projections that emit docs) will emit those docs into all user projects.