Add more code examples into the XML documentation

[OlegRa]

The built-in C# XML documentation allows developers to provide code examples that will be visible to the SDK users in VS IntelliSense tips. Right now SDK doesn't provide any code samples even for hard-to-use features. I'm open to accepting pull requests with such code samples. Let's make SDK better for new users together!

[natehitze]

@OlegRa Do you have any areas in mind to focus on for these examples?

[OlegRa]

@natehitze Old version of Alpaca documentation contains a lot of short examples for performing some basic tasks using different SDKs/languages. If you want, I can send you the latest version of such C# code snippets. I'm not sure how we can make them part of the documentation generated by DocFX but it would be nice if it will be possible.

Ideally, this code should be compilable because instead, we will have problems with outdated samples. AFAIR, code samples in the XML comments are not compiled and therefore we should find another way to keep these code samples up-to-date. I've used the hand-made script that runs against the old Alpaca documentation repo, get all C# code snippets, and compile them. But this script have to be run manually and it was part of my "official release" process. If we can automate it or verify documentation code correctness on each build it would be much better.

[drew887]

Ideally, this code should be compilable because instead, we will have problems with outdated samples. AFAIR, code samples in the XML comments are not compiled and therefore we should find another way to keep these code samples up-to-date. [...] If we can automate it or verify documentation code correctness on each build it would be much better.

@OlegRa not sure if you solved this elsewhere but in terms of validating tests/examples in docs, we're investigating using doctest for the other SDKs for this exact purpose. It looks like there's a community version of this for C# here; I haven't validated it myself yet but hopefully it will work here for a similar manner.