More examples in Q# API documentation comments

[cgranade]

Is your feature request related to a problem? Please describe.
Adding concrete examples to API documentation comments can help clarify how Q# functions and operations are to be used. For example, the documentation for Microsoft.Quantum.Arrays.ElementsAt lists how the function acts on a variety of arrays:

Where these examples are missing, or where additional examples may help explain complicated functionality, it would be good to add these examples to the Q# source for each function and operation.

List of candidate namespaces for examples:

• Microsoft.Quantum.Arrays
• Microsoft.Quantum.Convert
• Microsoft.Quantum.Measurement
• Microsoft.Quantum.Diagnostics
• Microsoft.Quantum.Logical
• Microsoft.Quantum.Math

For more details, see the API documentation section of the contribution guide.

[anonymousr007]

Hi @cgranade, I'm Rishabh, can you please elaborate little bit more ? I want to make a pull request of this issue 😄

[cgranade]

@anonymousr007: Thanks for reaching out! In general, this enhancement request is looking for API documentation (indicated by /// comments on Q# functions and operations in this repo and in the qsharp-runtime repo) to contain more examples of how to use each different part of the Q# libraries. Each different example is indicated using a /// # Example heading in the API documentation comments; for example, the above screenshot comes from the comment at https://github.dev/microsoft/QuantumLibraries/blob/aac552c8f904099ee3bc6b35c9617c3dac34add3/Standard/src/Arrays/Multidimensional.qs#L67-L67.

Would love for your contribution in this area, please let me know if there's anything I can do to help. Thank you!

[TonyHoldroyd]

@msoeken Ciao Mathias. I recently completed a workbook for one of Mariia's wonderful quantum katas, and she suggested I could contribute to this issue, so I'm writing to reach out about that. She also suggested that the Arrays namespace would be a good place to start. Please could you advise on the workflow here. Do I fork QuantumLibraries and add an example to a operation/function that needs one according to the protocol I can see there and then make a PR please?. Also, which editor do you advise for this. Thanks.

[msoeken]

@TonyHoldroyd Thanks for reaching out and your interest in working on this issue. The M.Q.Arrays namespace is a good place to start. I suggest to fork the repository, then create a new branch from main, e.g.,

git checkout -b apidocs

When you push this branch to your fork Github will assist you in creating a PR. Feel free to start the PR before completion and mark it as draft.

I am usually using Visual Studio Code to work on the Q# libraries.