Update doc comments in std library (#1401)

This PR updates doc comments in the standard library. It also adds
information to the readme file describing what to put in different
sections of doc comments.
This is mostly random updates to a few spots in the library rather than
a consistent sweep over all functions and operation. Mostly to solicit
feedback on changes needed.

---------

Co-authored-by: Dmitry Vasilevsky <[email protected]>
Co-authored-by: Scott Carda <[email protected]>
Co-authored-by: César Zaragoza Cortés <[email protected]>

compiler/qsc_doc_gen/src/generate_docs/tests.rs

@@ -24,7 +24,7 @@ fn docs_generation() {
         qsharp.kind: function
         qsharp.namespace: Microsoft.Quantum.Core
         qsharp.name: Length
-        qsharp.summary: "Returns the number of elements in an array."
+        qsharp.summary: "Returns the number of elements in the input array `a`."
         ---
 
         # Length function
@@ -36,14 +36,19 @@ fn docs_generation() {
         ```
 
         ## Summary
-        Returns the number of elements in an array.
+        Returns the number of elements in the input array `a`.
 
         ## Input
         ### a
         Input array.
 
         ## Output
-        The total count of elements in an array.
+        The total number of elements in the input array `a`.
+
+        ## Example
+        ```qsharp
+        Message($"{ Length([0, 0, 0]) }"); // Prints 3
+        ```
     "#]]
     .assert_eq(full_contents.as_str());
 }

compiler/qsc_eval/src/tests.rs

@@ -439,16 +439,16 @@ fn block_qubit_use_array_invalid_count_expr() {
                             0,
                         ),
                         span: Span {
-                            lo: 1566,
-                            hi: 1623,
+                            lo: 2034,
+                            hi: 2091,
                         },
                     },
                 ),
                 [
                     Frame {
                         span: Span {
-                            lo: 1566,
-                            hi: 1623,
+                            lo: 2034,
+                            hi: 2091,
                         },
                         id: StoreItemId {
                             package: PackageId(

library/README.md

@@ -19,3 +19,30 @@ One notable exception to this is the `Microsoft.Quantum.Core.Length` function, w
 The library includes a set of one- and two-qubit gates represented as `__quantum__qis__*__body` or `__quantum__qis__*__adj` QIR declarations. The expectation is that these gates form a common QIR API surface that Q# is compiled into. Any target would either need to support these quantum gate instructions natively or provide a QIR definition of that gate instruction in terms of supported native gates. These definitions can then be linked with the QIR program via LLVM tools and resolve to the target specific gate set. This approach provides broader compatibility at the QIR level and avoids the need for front end language targetting; as a result, this Q# library design is not expected to require any target packages or operation substitution.
 
 To avoid using any opaque array types in the quantum gate instruction set, the library utilizes decomposition strategies to express the Q# controlled specialization (which allows an arbitrary number of controls) in terms of singly- and doubly-controlled gates. While this makes simulation somewhat more expensive in terms of allocating extra controls and performing more operations, it more closely matches the patterns used by hardware and provides better API surface for QIR programs to have hardware compatibility.
+
+### Doc comments
+
+Use the following guidance when providing doc comments for functions and operations in the standard library. These doc comments are used to generate standard library documentation automatically.
+
+| Section        | LaTeX allowed? | Mandatory? | What is it for
+|---------------:|:--------------:|:----------:|----------------
+| Summary        | No             | Yes        | Short summary of the functionality provided.
+| Description    | Yes            | No         | Detailed explanation of the functionality provided.
+| Remarks        | Yes            | No         | General knowledge that may be useful for understanding of the functionality provided.
+| Type Parameters| No             | No         | Description of type parameters (for each type parameter).
+| Input          | No             | No         | Description of input parameters (for each input parameter)
+| Output         | No             | No         | Description of the output.
+| Example        | No             | No         | Example(s) of use. Should be a code fragment that compiles.
+| References     | No             | No         | References to papers and other information published on the web or elsewhere.
+| See Also       | No             | No         | References to other functions of the standard library that are similar or relevant.
+
+* Only `Summary` section is mandatory. There's no need to include other
+  sections just to repeat the information that is already stated in the summary.
+* For sections where LaTeX is not allowed, Unicode characters may be used
+  to represent mathematical formulas even though it is not recommended in
+  general. These sections are used in places where LaTeX rendering is
+  not supported.
+* For sections where LaTeX is supported, unicode characters may be used to
+  represent mathematical formulas only if the rendering fidelity is
+  not compromised.
+* Use playground to check documentation rendering.

library/core/core.qs

@@ -3,20 +3,32 @@
 
 namespace Microsoft.Quantum.Core {
     /// # Summary
-    /// Returns the number of elements in an array.
+    /// Returns the number of elements in the input array `a`.
     ///
     /// # Input
     /// ## a
     /// Input array.
     ///
     /// # Output
-    /// The total count of elements in an array.
+    /// The total number of elements in the input array `a`.
+    ///
+    /// # Example
+    /// ```qsharp
+    /// Message($"{ Length([0, 0, 0]) }"); // Prints 3
+    /// ```
     function Length<'T>(a : 'T[]) : Int {
         body intrinsic;
     }
 
     /// # Summary
-    /// Creates an array of given length with all elements equal to given value.
+    /// Creates an array of given `length` with all elements equal to given
+    /// `value`. `length` must be a non-negative integer.
+    ///
+    /// # Description
+    /// Use this function to create an array of length `length` where each
+    /// element is equal to `value`. This way of creating an array is preferred
+    /// over other methods if all elements of the array must be the same and
+    /// the length is known upfront.
     ///
     /// # Input
     /// ## value
@@ -28,8 +40,8 @@ namespace Microsoft.Quantum.Core {
     /// A new array of length `length`, such that every element is `value`.
     ///
     /// # Example
-    /// The following code creates an array of 3 Boolean values, each equal to `true`:
     /// ```qsharp
+    /// // Create an array of 3 Boolean values, each equal to `true`
     /// let array = Repeated(true, 3);
     /// ```
     function Repeated<'T>(value : 'T, length : Int) : 'T[] {

library/std/arrays.qs

@@ -203,7 +203,7 @@ namespace Microsoft.Quantum.Arrays {
     ///
     /// # Example
     /// ```qsharp
-    ///  let evensCount = Count(x -> x % 2 == 0, [1, 3, 6, 7, 9]);
+    /// let evensCount = Count(x -> x % 2 == 0, [1, 3, 6, 7, 9]);
     /// // evensCount is 1.
     /// ```
     function Count<'T>(predicate : ('T -> Bool), array : 'T[]) : Int {

library/std/canon.qs

@@ -173,10 +173,12 @@ namespace Microsoft.Quantum.Canon {
     /// This operation can be simulated by the unitary matrix
     /// $$
     /// \begin{align}
-    ///     1 & 0 & 0 & 0 \\\\
-    ///     0 & 1 & 0 & 0 \\\\
-    ///     0 & 0 & 0 & -i \\\\
-    ///     0 & 0 & i & 0
+    ///     \left(\begin{matrix}
+    ///         1 & 0 & 0 & 0 \\\\
+    ///         0 & 1 & 0 & 0 \\\\
+    ///         0 & 0 & 0 & -i \\\\
+    ///         0 & 0 & i & 0
+    ///      \end{matrix}\right)
     /// \end{align},
     /// $$
     /// where rows and columns are organized as in the quantum concepts guide.
@@ -208,10 +210,12 @@ namespace Microsoft.Quantum.Canon {
     /// This operation can be simulated by the unitary matrix
     /// $$
     /// \begin{align}
-    ///     1 & 0 & 0 & 0 \\\\
-    ///     0 & 1 & 0 & 0 \\\\
-    ///     0 & 0 & 1 & 0 \\\\
-    ///     0 & 0 & 0 & -1
+    ///     \left(\begin{matrix}
+    ///         1 & 0 & 0 & 0 \\\\
+    ///         0 & 1 & 0 & 0 \\\\
+    ///         0 & 0 & 1 & 0 \\\\
+    ///         0 & 0 & 0 & -1
+    ///     \end{matrix}\right)
     /// \end{align},
     /// $$
     /// where rows and columns are organized as in the quantum concepts guide.
@@ -432,8 +436,17 @@ namespace Microsoft.Quantum.Canon {
     }
 
     /// # Summary
-    /// Applies a unitary operation on the target,
-    /// controlled on a state specified by a given bit mask.
+    /// Applies `oracle` on `target` when `controlRegister`
+    /// is in the state specified by `bits`.
+    ///
+    /// # Description
+    /// Applies a unitary operation `oracle` on the `target`, controlled
+    /// on a state specified by a given bit mask `bits`.
+    /// The bit at `bits[i]` corresponds to qubit at `controlRegister[i]`.
+    /// The pattern given by `bits` may be shorter than `controlRegister`,
+    /// in which case additional control qubits are ignored (that is, neither
+    /// controlled on |0⟩ nor |1⟩).
+    /// If `bits` is longer than `controlRegister`, an error is raised.
     ///
     /// # Input
     /// ## bits
@@ -445,14 +458,16 @@ namespace Microsoft.Quantum.Canon {
     /// ## controlRegister
     /// A quantum register that controls application of `oracle`.
     ///
-    /// # Remarks
-    /// The pattern given by `bits` may be shorter than `controlRegister`,
-    /// in which case additional control qubits are ignored (that is, neither
-    /// controlled on $\ket{0}$ nor $\ket{1}$).
-    /// If `bits` is longer than `controlRegister`, an error is raised.
-    ///
-    /// For example, `bits = [0,1,0,0,1]` means that `oracle` is applied if and only if `controlRegister`
-    /// is in the state $\ket{0}\ket{1}\ket{0}\ket{0}\ket{1}$.
+    /// # Example
+    /// ```qsharp
+    /// // When bits = [1,0,0] oracle is applied if and only if controlRegister
+    /// // is in the state |100⟩.
+    /// use t = Qubit();
+    /// use c = Qubit[3];
+    /// X(c[0]);
+    /// ApplyControlledOnBitString([true, false, false], X, c, t);
+    /// Message($"{M(t)}"); // Prints `One` since oracle `X` was applied.
+    /// ```
     operation ApplyControlledOnBitString<'T>(
         bits : Bool[],
         oracle : ('T => Unit is Adj + Ctl),

library/std/convert.qs

@@ -6,13 +6,27 @@ namespace Microsoft.Quantum.Convert {
     open Microsoft.Quantum.Math;
 
     /// # Summary
-    /// Converts a given integer to an equivalent double-precision floating-point number.
+    /// Converts a given integer `number` to an equivalent
+    /// double-precision floating-point number.
+    ///
+    /// # Description
+    /// Converts a given integer to a double-precision floating point number.
+    /// Please note that the double-precision representation may have fewer
+    /// bits allocated to represent [significant digits](https://en.wikipedia.org/wiki/Significand)
+    /// so the conversion may be approximate for large numbers. For example,
+    /// the current simulator converts 4,611,686,018,427,387,919 = 2^64+15
+    /// to 4,611,686,018,427,387,904.0 = 2^64.
+    ///
+    /// # Example
+    /// ```qsharp
+    /// Message($"{IntAsDouble(1)}"); // Prints 1.0 rather than 1
+    /// ```
     function IntAsDouble(number : Int) : Double {
         body intrinsic;
     }
 
     /// # Summary
-    /// Converts a given integer to an equivalent big integer.
+    /// Converts a given integer `number` to an equivalent big integer.
     function IntAsBigInt(number : Int) : BigInt {
         body intrinsic;
     }
@@ -48,7 +62,8 @@ namespace Microsoft.Quantum.Convert {
     }
 
     /// # Summary
-    /// Produces a non-negative integer from a string of bits in little endian format.
+    /// Produces a non-negative integer from a string of bits in little-endian format.
+    /// `bits[0]` represents the least significant bit.
     ///
     /// # Input
     /// ## bits

library/std/core.qs

@@ -19,11 +19,15 @@ namespace Microsoft.Quantum.Core {
     ///
     /// Note that the defined start value of a range is the same as the first element of the sequence,
     /// unless the range specifies an empty sequence (for example, 2 .. 1).
+    ///
+    /// # Example
+    /// ```qsharp
+    /// Message($"{ RangeStart(7..-1..3) }"); // Prints 7
+    /// ```
     function RangeStart(r : Range) : Int {
         r::Start
     }
 
-
     /// # Summary
     /// Returns the defined end value of the given range,
     /// which is not necessarily the last element in the sequence.

library/std/logical.qs

@@ -4,7 +4,8 @@
 namespace Microsoft.Quantum.Logical {
 
     /// # Summary
-    /// Returns the boolean exclusive disjunction (XOR) of two input boolean values.
+    /// Returns the boolean exclusive disjunction (eXclusive OR, XOR)
+    /// of two input boolean values.
     ///
     /// # Input
     /// ## first
@@ -16,9 +17,11 @@ namespace Microsoft.Quantum.Logical {
     /// # Output
     /// A `Bool` which is `true` if and only if exactly one of `first` and `second` is `true`.
     ///
+    /// # Remarks
+    /// In Q#, `Xor(a, b)` is equivalent to `a != b`.
+    ///
     /// # Example
     /// ```qsharp
-    ///
     /// let result = Xor(true, false);
     /// // result is true
     /// ```

library/std/math.qs

@@ -10,11 +10,16 @@ namespace Microsoft.Quantum.Math {
     //
 
     /// # Summary
-    /// Represents the ratio of the circumference of a circle to its diameter.
+    /// Returns a double-precision approximation of the
+    /// matematical constant 𝝅 ≈ 3.14159265358979323846
     ///
-    /// # Output
-    /// A double-precision approximation of the circumference of a circle
-    /// to its diameter, π ≈ 3.14159265358979323846.
+    /// # Remarks
+    /// Mathematical constant 𝝅 represents the ratio of the circumference
+    /// of a circle to its diameter. It is useful in many applications
+    /// such as rotations and complex arithmetic.
+    ///
+    /// # References
+    /// [Wikipedia article - Pi](https://en.wikipedia.org/wiki/Pi)
     ///
     /// # See Also
     /// - Microsoft.Quantum.Math.E
@@ -23,11 +28,15 @@ namespace Microsoft.Quantum.Math {
     }
 
     /// # Summary
-    /// Returns the natural logarithmic base to double-precision.
+    /// Returns a double-precision approximation of the
+    /// mathematical constant 𝒆 ≈ 2.7182818284590452354
     ///
-    /// # Output
-    /// A double-precision approximation of the natural logarithmic base,
-    /// e ≈ 2.7182818284590452354.
+    /// # Remarks
+    /// Mathematical constant 𝒆 is the base of the natural logarithm
+    /// also known as the Euler's number
+    ///
+    /// # References
+    /// [Wikipedia article - e](https://en.wikipedia.org/wiki/E_(mathematical_constant))
     ///
     /// # See Also
     /// - Microsoft.Quantum.Math.PI
@@ -36,10 +45,14 @@ namespace Microsoft.Quantum.Math {
     }
 
     /// # Summary
-    /// Returns the natural logarithm of 2.
+    /// Returns a double-precision approximation of the constant
+    /// ㏑2 ≈ 0.6931471805599453
     ///
-    /// # Output
-    /// Returns a `Double` equal to 0.6931471805599453.
+    /// # Remarks
+    /// ㏑2 is the natural logarithm of 2, or the logarithm of 2 base 𝒆.
+    ///
+    /// # References
+    /// [Wikipedia article - Natural logarithm](https://en.wikipedia.org/wiki/Natural_logarithm)
     function LogOf2() : Double {
         0.6931471805599453
     }
@@ -383,7 +396,7 @@ namespace Microsoft.Quantum.Math {
 
     /// # Summary
     /// Returns the nearest integer to the specified number.
-    /// For example: Floor(3.7) = 4; Floor(-3.7) = -4
+    /// For example: Round(3.7) = 4; Round(-3.7) = -4
     function Round(value : Double) : Int {
         let (truncated, remainder, isPositive) = ExtendedTruncation(value);
         if AbsD(remainder) <= 1e-15 {