From 7884d560797313b3bc003748f4dbe443e3e59043 Mon Sep 17 00:00:00 2001
From: davidedellagiustina <davide@dellagiustina.com>
Date: Sat, 10 Feb 2024 22:59:23 +0000
Subject: [PATCH] Better documentation for all the examples

---
 src/examples/embedded_heuristic.py         | 5 +++--
 src/examples/grover_search_known_m.py      | 6 ++----
 src/examples/grover_search_unknown_m.py    | 7 ++++---
 src/examples/oracle_construction.py        | 4 +---
 src/examples/quantum_counting.py           | 5 ++---
 src/examples/quantum_counting_advanced.py  | 5 ++---
 src/examples/quantum_faceted_navigation.py | 7 ++-----
 7 files changed, 16 insertions(+), 23 deletions(-)

diff --git a/src/examples/embedded_heuristic.py b/src/examples/embedded_heuristic.py
index a0ba263..ddf9c34 100644
--- a/src/examples/embedded_heuristic.py
+++ b/src/examples/embedded_heuristic.py
@@ -1,6 +1,7 @@
-'''TODO
+'''Find the stable models of an ASP program during faceted navigation using the Rot gate from QWMC.
+
+Reference: Example 5.2.2 in the thesis.
 '''
-# TODO: Docstring.
 
 from src import qasp
 from src.examples.util import tab, pause
diff --git a/src/examples/grover_search_known_m.py b/src/examples/grover_search_known_m.py
index d451899..001be6d 100644
--- a/src/examples/grover_search_known_m.py
+++ b/src/examples/grover_search_known_m.py
@@ -1,8 +1,6 @@
-'''Find the models of an ASP program using the naive Grover search algorithm.
+'''Find the stable models of an ASP program using naive Grover Search.
 
-Exapmple 4.1.1 in the thesis document shows how to use the Grover Search algorithm \
-to find the stable models of an ASP program. This example provides an implementation \
-of that technique, to show how it can be used in practice.
+Reference: Example 4.1.1 in the thesis.
 '''
 
 from src import qasp
diff --git a/src/examples/grover_search_unknown_m.py b/src/examples/grover_search_unknown_m.py
index f7295b6..33aafdd 100644
--- a/src/examples/grover_search_unknown_m.py
+++ b/src/examples/grover_search_unknown_m.py
@@ -1,7 +1,8 @@
-'''Find the models of an ASP program using the Grover search algorithm, but without knowing the \
-    number M of solutions.
+'''Find the stable models of an ASP program using QSearch on the naive Grover Search algorithm, \
+without requiring the number M of solutions to be known in advance.
+
+Reference: Example 5.2.1 in the thesis.
 '''
-# TODO: Better docstring with reference to the corresponding example in the thesis.
 
 from src import qasp
 from src.examples.util import tab, pause
diff --git a/src/examples/oracle_construction.py b/src/examples/oracle_construction.py
index 7d0cd74..d71eb08 100644
--- a/src/examples/oracle_construction.py
+++ b/src/examples/oracle_construction.py
@@ -1,8 +1,6 @@
 '''Grover Search with a quantum oracle built from the classical procedure.
 
-Example 4.2.1 in the thesis shows how to build a quantum oracle for a trivial ASP program using the
-classical procedure. This example applies the Grover Search algorithm in order to demonstrate the
-correctness of the built operator.
+Reference: Example 4.2.1 in the thesis.
 '''
 
 import copy
diff --git a/src/examples/quantum_counting.py b/src/examples/quantum_counting.py
index 2dbc99a..f9008ec 100644
--- a/src/examples/quantum_counting.py
+++ b/src/examples/quantum_counting.py
@@ -1,7 +1,6 @@
-'''Count the number of stable models of an ASP program using the naive Quantum Counting algorithm.
+'''Count the number of stable models of an ASP program using naive Quantum Counting.
 
-Example 4.1.2 in the thesis shows how to use the Quantum Counting algorithm to count the stable \
-models of a given ASP program. This example implements that technique.
+Reference: Example 4.1.2 in the thesis.
 '''
 
 import math
diff --git a/src/examples/quantum_counting_advanced.py b/src/examples/quantum_counting_advanced.py
index 193b793..6338165 100644
--- a/src/examples/quantum_counting_advanced.py
+++ b/src/examples/quantum_counting_advanced.py
@@ -1,7 +1,6 @@
-'''Count the number of stable models of an ASP program using the naive Quantum Counting algorithm.
+'''Count the number of stable models of an ASP program using naive Quantum Counting.
 
-Since example `quantum_counting' uses only 2 qubits, the precision of the resulting estimate of M \
-is very low. This example improves the estimate precision by adding a few qubits to the circuit.
+Improved estimation prevision with respect to `quantum_counting'.
 '''
 
 from src import qasp
diff --git a/src/examples/quantum_faceted_navigation.py b/src/examples/quantum_faceted_navigation.py
index ca4c92e..7edaec5 100644
--- a/src/examples/quantum_faceted_navigation.py
+++ b/src/examples/quantum_faceted_navigation.py
@@ -1,9 +1,6 @@
-'''Count the number of stable models of an ASP program after some navigation steps, using the QWMC \
-circuit.
+'''Count the number of stable models of an ASP program during faceted navigation using QWMC.
 
-This example implements Example 5.1.1 in the thesis document, where we use the Quanutm WMC circuit \
-to estimate the number of solutions to a program after navigating its solution space using a route \
-delta.
+Reference: Example 5.1.1 in the thesis.
 '''
 
 import math