[docs] Add C++ docs for get_state(), sample() and observe()

[lmondada]

closes #2139

Description

Added entries for the three functions to docs/sphinx/api/languages/cpp_api.rst, along with very minor modifications of two of the relevant header files. Sphinx now generates entries for these functions in the C++ API reference.

For observe and sample, I was unsure about how many overloads should be exposed, both to avoid unnecessary clutter in the docs and also to avoid clashes in Sphinx's name resolution. ATM all overloads (3) of sample() are exposed (this requires sample_options to be exposed, too), whereas for observe() the overloads that either:

• take a DistributionType template (afaik Doxygen cannot distinguish overloads that only differ in their return type), or
• take a ArgumentSet parameter (would require exposing this type synonym)

are excluded.

Let me know if you want me to adjust the list of exposed overloads, the ordering of the declarations or any other changes. Happy to modify it as you prefer.

Note: There are further related functions that are not exposed (e.g. their _async counterparts). Let me know if I should raise a further issue about those.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

CLA Assistant Lite bot All Contributors have signed the CLA.

[lmondada]

I have read the Contributor License Agreement and I hereby accept the Terms.

[bmhowe23]

/ok to test

Command Bot: Processing...

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[schweitzpgi]

/ok to test

Command Bot: Processing...

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[lmondada]

Hi @schweitzpgi and @bmhowe23 !

Thanks for your reviews. All CI checks are currently passing, so I won't be touching this PR anymore. Feel free to have a look whenever you have time, this is very low priority.

Bettina mentioned to me that a lot of the C++ API isn't documented on purpose, as future breaking changes aren't excluded -- feel free to ignore and close this PR in this case.

Of course also happy to modify and address any comments you may have.