Feature branch cleanup (#582)

* Fixes #570. (#572)

* Fixes #571. (#573)

* Add DevSkim scanning (#576)

* Examples in fixed-point conversion functions.

* API review April 2022 (#561)

* API review April 2022

* Apply suggestions from code review

Co-authored-by: Mariia Mykhailova <mamykhai@microsoft.com>

* Update api-design-2022-04.md

* Update api-design-2022-04.md

Co-authored-by: Mariia Mykhailova <mamykhai@microsoft.com>

* Fixes #580. (#581)

* Address reviewer's feedback.

Co-authored-by: Angela Burton <anjbur@users.noreply.github.com>
Co-authored-by: Mariia Mykhailova <mamykhai@microsoft.com>

Numerics/src/FixedPoint/Convert.qs

@@ -15,6 +15,14 @@ namespace Microsoft.Quantum.Convert {
     /// Assumed number of fractional bits.
     /// ## value
     /// Value to be approximated.
+    ///
+    /// # Example
+    /// Note that the first element in the Boolean array is the least-significant bit.
+    /// ```qsharp
+    /// let bits = FixedPointAsBoolArray(2, 2,  1.25); // bits = [true, false, true, false]
+    /// let bits = FixedPointAsBoolArray(2, 2,  1.3);  // bits = [true, false, true, false], approximated
+    /// let bits = FixedPointAsBoolArray(2, 2, -1.75); // bits = [true, false, false, true], two's complement
+    /// ```
     function FixedPointAsBoolArray(integerBits : Int, fractionalBits : Int, value : Double) : Bool[] {
         let numBits = integerBits + fractionalBits;
         let sign = value < 0.0;
@@ -47,6 +55,13 @@ namespace Microsoft.Quantum.Convert {
     /// Assumed number of integer bits (including the sign bit).
     /// ## bits
     /// Bit-string representation of approximated number.
+    ///
+    /// # Example
+    /// Note that the first element in the Boolean array is the least-significant bit.
+    /// ```qsharp
+    /// let value = BoolArrayAsFixedPoint(2, [true, false, true, false]); // value =  1.25
+    /// let value = BoolArrayAsFixedPoint(2, [true, false, false, true]); // value = -1.75
+    /// ```
     function BoolArrayAsFixedPoint(integerBits : Int, bits : Bool[]) : Double {
         let numBits = Length(bits);
         let intPart = (Tail(bits) ? -(1 <<< (numBits - 1)) | 0) + BoolArrayAsInt(Most(bits));
@@ -63,6 +78,12 @@ namespace Microsoft.Quantum.Convert {
     /// Assumed number of fractional bits.
     /// ## value
     /// Value to be approximated.
+    ///
+    /// # Example
+    /// ```qsharp
+    /// let value = DoubleAsFixedPoint(2, 2, 1.3); // value = 1.25
+    /// let value = DoubleAsFixedPoint(2, 2, 0.8); // value = 0.75
+    /// ```
     function DoubleAsFixedPoint(integerBits : Int, fractionalBits : Int, value : Double) : Double {
         return BoolArrayAsFixedPoint(integerBits, FixedPointAsBoolArray(integerBits, fractionalBits, value));
     }

Numerics/tests/FixedPointTests.qs

@@ -51,6 +51,19 @@ namespace Microsoft.Quantum.Tests {
         NearEqualityFactD(PrepareAsSignedAndMeasure(0b1111, qsFxP), -0.25);
     }
 
+    @Test("QuantumSimulator")
+    operation FixedPointConversionTest() : Unit {
+        AllEqualityFactB(FixedPointAsBoolArray(2, 2,  1.25), [true, false, true, false], "FixedPointAsBoolArray failed");
+        AllEqualityFactB(FixedPointAsBoolArray(2, 2,  1.3), [true, false, true, false], "FixedPointAsBoolArray failed");
+        AllEqualityFactB(FixedPointAsBoolArray(2, 2, -1.75), [true, false, false, true], "FixedPointAsBoolArray failed");
+
+        NearEqualityFactD(BoolArrayAsFixedPoint(2, [true, false, true, false]), 1.25);
+        NearEqualityFactD(BoolArrayAsFixedPoint(2, [true, false, false, true]), -1.75);
+
+        NearEqualityFactD(DoubleAsFixedPoint(2, 2, 1.3), 1.25);
+        NearEqualityFactD(DoubleAsFixedPoint(2, 2, 0.8), 0.75);
+    }
+
     @Test("ToffoliSimulator")
     operation CompareGreaterThanFxPTest() : Unit {
         for a in [1.2, 3.9, 3.14159, -0.6, -4.5, -3.1931, 0.0] {