DynamicDependencies: Flesh out Intellisense .xml with doccomments

[DrusTheAxe]

VS Intellisense provides syntax info from code / prototypes / winmd / etc but needs the build\Intellisense*.xml files to provide (human authored) descriptions. Those should be defined from doccomments in .h / .idl / .cs but we currently need to manually carry the doccomment info from source to the Intellisense .xml files. Not a big deal for DynamicDependencies given the small API surface

The doccomments are already in MsixDynamicDependency.h and M.AM.DynamicDependency.idl just need the info propogated to the Intellisense .xml files. See the discussion in #887 (comment) for more details

[sylveon]

For the header files, one can write Doxygen comments instead. VS and every C++ IDE will pick those up, instead of being in a VS specific format. For the .winmd, keep shipping XML documentation files and some day microsoft/cppwinrt#933 will come.

[DrusTheAxe]

MsixDynamicDependencies.h is chock full of Doxygen goodness. I didn't know VS would automatically pick that up. I'll have to check that out. Thanks!

[sylveon]

Yup, it's been supported since March last year! https://devblogs.microsoft.com/cppblog/doxygen-and-xml-doc-comment-support/

[DrusTheAxe]

That's excellent. I'm a long time fan of Doxygen :-)

Alas, that doesn't help for our WinRT APIs, so keeping this issue open to track it.

But thanks for the info!

[DrusTheAxe]

Reassigning to zaryaf for follow up (all the build\nuspecs\intellisense files need updating)

[BenJKuhn]

Howard Kapustein (@DrusTheAxe) , Charles Milette (@sylveon) what's the localization story for doxygen-based comments? Can we still easily scrape and provide localized versions, and is there existing infrastructure to support that?

[DrusTheAxe]

What's the localization story for Intellisense?

What's the localization story for https://docs.microsoft.com? e.g. https://docs.microsoft.com/windows/windows-app-sdk/api/win32/mddbootstrap/nf-mddbootstrap-mddbootstrapinitialize

We usually spec APIs as symbols with doxygen-style comments. Once approved devs copy the code snippet(s) to .h/.idl/etc and documentation writers use the same information to author docs on https://docs.microsoft.com. For Flat-C APIs this provides rich API information in the header itself which is often convenient when developing and debugging use. What's expected for WinRT e.g. do .winmd support doc-comments? Embedded or link to docs?

Should we stop doing this?

[angelazhangmsft]

This is being tracked internally at https://task.ms/565220 for our documentation system to generate Intellisense files for Windows App SDK APIs.

Feel free to open a separate feature request to support in-code intellisense documentation (e.g., Doxygen)