Update API docs with more examples.

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<Qubit>` is identical to
-    /// <xref:microsoft.quantum.intrinsic.i>.
-    ///
     /// # See Also
     /// - Microsoft.Quantum.Intrinsic.I
     operation NoOp<'T>(input : 'T) : Unit is Adj + Ctl {

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 (...) {

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;
     }

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);
 

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);
 
 }

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;
     }