From 176dd80bd51a80b50c5e58285459ea8f40730bfa Mon Sep 17 00:00:00 2001 From: Christopher Granade Date: Thu, 20 May 2021 15:24:28 -0700 Subject: [PATCH] Update API docs with more examples. --- src/Simulation/QSharpFoundation/Canon/NoOp.qs | 5 --- .../QSharpFoundation/Diagnostics/Assert.qs | 12 +++++++ .../QSharpFoundation/Diagnostics/Dump.qs | 36 +++++++++++++++---- .../QSharpFoundation/Diagnostics/UnitTests.qs | 8 +++++ src/Simulation/QSharpFoundation/Math/Types.qs | 6 ++++ src/Simulation/QSharpFoundation/Message.qs | 8 +++++ 6 files changed, 64 insertions(+), 11 deletions(-) diff --git a/src/Simulation/QSharpFoundation/Canon/NoOp.qs b/src/Simulation/QSharpFoundation/Canon/NoOp.qs index b9a778f6e26..9b83852176d 100644 --- a/src/Simulation/QSharpFoundation/Canon/NoOp.qs +++ b/src/Simulation/QSharpFoundation/Canon/NoOp.qs @@ -21,11 +21,6 @@ namespace Microsoft.Quantum.Canon { /// ## input /// A value to be ignored. /// - /// # Remarks - /// In almost all cases, the type parameter for `NoOp` needs to be specified - /// explicitly. For instance, `NoOp` is identical to - /// . - /// /// # See Also /// - Microsoft.Quantum.Intrinsic.I operation NoOp<'T>(input : 'T) : Unit is Adj + Ctl { diff --git a/src/Simulation/QSharpFoundation/Diagnostics/Assert.qs b/src/Simulation/QSharpFoundation/Diagnostics/Assert.qs index 994dd2170f2..f79281280ed 100644 --- a/src/Simulation/QSharpFoundation/Diagnostics/Assert.qs +++ b/src/Simulation/QSharpFoundation/Diagnostics/Assert.qs @@ -24,6 +24,18 @@ namespace Microsoft.Quantum.Diagnostics { /// # See Also /// - Microsoft.Quantum.Diagnostics.AssertMeasurementProbability /// - Microsoft.Quantum.Intrinsic.Measure + /// + /// # Example + /// The following snippet will execute without errors on the full-state + /// simulator: + /// ```qsharp + /// use q = Qubit(); + /// within { + /// H(q); + /// } apply { + /// AssertMeasurement([PauliX], [q], Zero, "Expected |+⟩ state."); + /// } + /// ``` operation AssertMeasurement(bases : Pauli[], qubits : Qubit[], result : Result, msg : String) : Unit is Adj + Ctl { body (...) { diff --git a/src/Simulation/QSharpFoundation/Diagnostics/Dump.qs b/src/Simulation/QSharpFoundation/Diagnostics/Dump.qs index 316b3305290..47109c3b503 100644 --- a/src/Simulation/QSharpFoundation/Diagnostics/Dump.qs +++ b/src/Simulation/QSharpFoundation/Diagnostics/Dump.qs @@ -10,9 +10,6 @@ namespace Microsoft.Quantum.Diagnostics { /// ## location /// Provides information on where to generate the machine's dump. /// - /// # Output - /// None. - /// /// # Remarks /// This method allows you to dump information about the current status of the /// target machine into a file or some other location. @@ -25,6 +22,20 @@ namespace Microsoft.Quantum.Diagnostics { /// the path to a file in which it will write the wave function as a /// one-dimensional array of complex numbers, in which each element represents /// the amplitudes of the probability of measuring the corresponding state. + /// + /// # Example + /// When run on the full-state simulator, the following snippet dumps + /// the Bell state $(\ket{00} + \ket{11}) / \sqrt{2}$ to the console: + /// ```qsharp + /// use left = Qubit(); + /// use right = Qubit(); + /// within { + /// H(left); + /// CNOT(left, right); + /// } apply { + /// DumpMachine(); + /// } + /// ``` function DumpMachine<'T> (location : 'T) : Unit { body intrinsic; } @@ -38,9 +49,6 @@ namespace Microsoft.Quantum.Diagnostics { /// ## qubits /// The list of qubits to report. /// - /// # Output - /// None. - /// /// # Remarks /// This method allows you to dump the information associated with the state of the /// given qubits into a file or some other location. @@ -56,6 +64,22 @@ namespace Microsoft.Quantum.Diagnostics { /// the amplitudes of the probability of measuring the corresponding state. /// If the given qubits are entangled with some other qubit and their /// state can't be separated, it just reports that the qubits are entangled. + /// + /// # Example + /// When run on the full-state simulator, the following snippet dumps + /// the Bell state $(\ket{00} + \ket{11}) / \sqrt{2}$ to the console: + /// ```qsharp + /// use left = Qubit(); + /// use right = Qubit(); + /// within { + /// H(left); + /// CNOT(left, right); + /// } apply { + /// // The () input here denotes that the state dumped by the + /// // full-state simulator should be reported to the console. + /// DumpRegister((), [left, right]); + /// } + /// ``` function DumpRegister<'T> (location : 'T, qubits : Qubit[]) : Unit { body intrinsic; } diff --git a/src/Simulation/QSharpFoundation/Diagnostics/UnitTests.qs b/src/Simulation/QSharpFoundation/Diagnostics/UnitTests.qs index 9b94aa84d9c..176278a06c2 100644 --- a/src/Simulation/QSharpFoundation/Diagnostics/UnitTests.qs +++ b/src/Simulation/QSharpFoundation/Diagnostics/UnitTests.qs @@ -12,6 +12,14 @@ namespace Microsoft.Quantum.Diagnostics { /// The name has to be either one of the known targets, or a fully qualified name. /// Known targets are: QuantumSimulator, ToffoliSimulator, ResourcesEstimator. /// + /// # Example + /// The following is a unit test that checks if `2 + 3` is `5`: + /// ```qsharp + /// @Test("QuantumSimulator") + /// function AdditionIsCorrect() : Unit { + /// EqualityFactI(2 + 3, 5, "Addition did not work correctly."); + /// } + /// ``` @Attribute() newtype Test = (ExecutionTarget : String); diff --git a/src/Simulation/QSharpFoundation/Math/Types.qs b/src/Simulation/QSharpFoundation/Math/Types.qs index 722aba91eb8..5383426fc87 100644 --- a/src/Simulation/QSharpFoundation/Math/Types.qs +++ b/src/Simulation/QSharpFoundation/Math/Types.qs @@ -11,6 +11,12 @@ namespace Microsoft.Quantum.Math { /// # Summary /// Represents a complex number by its real and imaginary components. /// The first element of the tuple is the real component, the second one - the imaginary component. + /// + /// # Example + /// The following snippet defines the imaginary unit $0 + 1i$: + /// ```qsharp + /// let imagUnit = Complex(0.0, 1.0); + /// ``` newtype Complex = (Real: Double, Imag: Double); } diff --git a/src/Simulation/QSharpFoundation/Message.qs b/src/Simulation/QSharpFoundation/Message.qs index 2a5a920491b..13cc71484cf 100644 --- a/src/Simulation/QSharpFoundation/Message.qs +++ b/src/Simulation/QSharpFoundation/Message.qs @@ -12,6 +12,14 @@ namespace Microsoft.Quantum.Intrinsic { /// # Remarks /// The specific behavior of this function is simulator-dependent, /// but in most cases the given message will be written to the console. + /// + /// # Example + /// The following causes `"Hello, world!"` to be reported (typically to + /// the console): + /// ```qsharp + /// let name = "world"; + /// Message($"Hello, {name}!"); + /// ``` function Message (msg : String) : Unit { body intrinsic; }