In general, the c++ docs are just brutally neglected.

[rlewkowicz]

First issue, pick anything. It's all C# for examples. I don't think I've ever seen a c++ example on inline documentation. Even when you choose a c++ doc type it's still C#.

https://learn.microsoft.com/en-us/uwp/api/windows.devices.enumeration.deviceinformation?view=winrt-22621 as an example

and then for C++ It's generally frustrating there's not even just basic usage and header files. I'm looking for methods, I find a snippet or I'm reverse engineering someone else's code and I need to know what something is and where it comes from.

Opencv for example. I want imshow.

https://docs.opencv.org/3.4/d7/dfc/group__highgui.html#ga453d42fe4cb60e5723281a89973ee563

It's all right here in front of me at a glance. Header file etc.

Your docs feel noisy almost. Then some things need interops and you don't really know until you google around and find blog posts from Raymond Chen if you're lucky.

There's literally no where to find functional examples. I tried searching github, google with site:github.com etc. I was lucky enough to find this: https://github.com/MicrosoftDocs/winrt-api/issues/378

And who knows if any of that even got fixed. He closes it and goes on to say "I've learned preferred way to use winrt::unbox_value to access properties"

How am I supposed to know this? If I'm not sitting next to world class MS C++ engineers, how am I supposed to meaningfully use and understand the WinRT c++ ecosystem?

[JaiganeshKumaran]

Have you read the C++/WinRT docs here? https://learn.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/intro-to-using-cpp-with-winrt.

[rlewkowicz]

Have you read the C++/WinRT docs here? https://learn.microsoft.com/en-us/windows/uwp/cpp-and-winrt-apis/intro-to-using-cpp-with-winrt.

This actually is helpful and had I read some of this first it would have eased much of my journey. I still stand by the need for basic examples and header includes. If an interop or header is required for a method to function or to handle its return values (Windows.Foundation.h) that should be mentioned.

[stevewhims]

Hi, @rlewkowicz. Here's a bit of info from me, in case it's of any use.

In general, the C++ docs are just brutally neglected.

There are several sets of docs that one might call "the C++ docs", each owned by the team that specializes in it. For example, Microsoft C++, C, and Assembler documentation covers Standard C++. Visual Studio tutorials | C++ comes from the VS angle. And C++/WinRT is about the projection of Windows Runtime APIs into C++ (which is also Standard C++, but that's a focused set of docs on that projection). That latter set is the content that Jaiganésh mentioned above.

I don't think I've ever seen an inline C++ example in documentation.

With your example of the DeviceInformation class, you did happen upon an example of a topic that contains a C# code example but not also a C++ one. There are lots of those. But here are some interesting figures. For C++ code examples, there are a little over 2,000 of them in Windows Runtime documentation; and nearly 7,000 just across the content repos that my team works in. For C# code examples, there are a little under 3,000 of them in Windows Runtime documentation; and a little over 4,000 across our content repos. So C# wins by 50% on the one hand; C++ wins by nearly 100% on the other. Again, that's just looking at my team's content. I'm not counting the Standard C++ and VS content I mentioned above, nor the content that's about the C# language. The comparison might be different if all that content were analyzed.

It's generally frustrating there's not even just basic usage and header files.

For Windows Runtime APIs, the pattern (as documented in the C++/WinRT content) is to include a header file named for the namespace that contains the API you're interested in. Plus, C++/WinRT is a particular language projection of WinRT with its own toolchain idiosyncrasies. For those reasons the Windows Runtime API reference mentions language-agnostic artifacts such as device families and API contracts and namespaces. It needn't mention C++/WinRT header files in particular. That info would arguably be redundant. And then of course the documentation for Win32 APIs is very different. There, the header file, lib, dll, etc. are all specified on every topic.

I was lucky enough to find this: https://github.com/MicrosoftDocs/winrt-api/issues/378 ... And who knows if any of that even got fixed.

Yes, in the thread the OP confirms that their issue was addressed and resolved.

Goes on to say "I've learned preferred way to use winrt::unbox_value to access properties" ... How am I supposed to know this?

FWIW, there's info about that in Boxing and unboxing values to IInspectable with C++/WinRT, and that topic links to the relevant API reference (which can also be found by searching for those API names, such as winrt::box_value).

I don't know whether any of that info helps! But I'll go ahead and close the issue for now, since I don't think there are pressing changes that need to be made to the docs with regard to C++.

Thanks! :) -Steve

[JaiganeshKumaran]

I still think it would be helpful to put little info buttons that link to the appropriate C++/WinRT docs page. Most people are not that aware of C++/WinRT and so if were to send an API reference page to someöne, they might not know how to use the API. For headers, I don't see any downside in mentioning winrt/Namespace.h while the language is set to C++/WinRT, even though that is technically redundant info.

The Windows Runtime is unfortunately not very well known. More friendly and understandable content is needed and that should use the right definition of WinRT just being an API delivery system and not something else.