base-modem,at: improve documentation on response processor methods

2 files changed, 98 insertions, 68 deletions

diff --git a/src/mm-base-modem-at.c b/src/mm-base-modem-at.c
index 101c9549..94bd3956 100644
--- a/src/mm-base-modem-at.c
+++ b/src/mm-base-modem-at.c
@@ -355,16 +355,17 @@ mm_base_modem_at_sequence (MMBaseModem *self,
 /* Response processor helpers */
 
 gboolean
-mm_base_modem_response_processor_string (MMBaseModem *self,
-                                         gpointer none,
-                                         const gchar *command,
-                                         const gchar *response,
-                                         gboolean last_command,
-                                         const GError *error,
-                                         GVariant **result,
-                                         GError **result_error)
+mm_base_modem_response_processor_string (MMBaseModem   *self,
+                                         gpointer       none,
+                                         const gchar   *command,
+                                         const gchar   *response,
+                                         gboolean       last_command,
+                                         const GError  *error,
+                                         GVariant     **result,
+                                         GError       **result_error)
 {
     if (error) {
+        /* Abort sequence on command error */
         *result_error = g_error_copy (error);
         return FALSE;
     }
@@ -374,16 +375,17 @@ mm_base_modem_response_processor_string (MMBaseModem *self,
 }
 
 gboolean
-mm_base_modem_response_processor_no_result (MMBaseModem *self,
-                                            gpointer none,
-                                            const gchar *command,
-                                            const gchar *response,
-                                            gboolean last_command,
-                                            const GError *error,
-                                            GVariant **result,
-                                            GError **result_error)
+mm_base_modem_response_processor_no_result (MMBaseModem   *self,
+                                            gpointer       none,
+                                            const gchar   *command,
+                                            const gchar   *response,
+                                            gboolean       last_command,
+                                            const GError  *error,
+                                            GVariant     **result,
+                                            GError       **result_error)
 {
     if (error) {
+        /* Abort sequence on command error */
         *result_error = g_error_copy (error);
         return FALSE;
     }
@@ -393,16 +395,17 @@ mm_base_modem_response_processor_no_result (MMBaseModem *self,
 }
 
 gboolean
-mm_base_modem_response_processor_no_result_continue (MMBaseModem *self,
-                                                     gpointer none,
-                                                     const gchar *command,
-                                                     const gchar *response,
-                                                     gboolean last_command,
-                                                     const GError *error,
-                                                     GVariant **result,
-                                                     GError **result_error)
+mm_base_modem_response_processor_no_result_continue (MMBaseModem   *self,
+                                                     gpointer       none,
+                                                     const gchar   *command,
+                                                     const gchar   *response,
+                                                     gboolean       last_command,
+                                                     const GError  *error,
+                                                     GVariant     **result,
+                                                     GError       **result_error)
 {
     if (error)
+        /* Abort sequence on command error */
         *result_error = g_error_copy (error);
 
     /* Return FALSE so that we keep on with the next steps in the sequence */
@@ -410,16 +413,17 @@ mm_base_modem_response_processor_no_result_continue (MMBaseModem *self,
 }
 
 gboolean
-mm_base_modem_response_processor_continue_on_error (MMBaseModem *self,
-                                                    gpointer none,
-                                                    const gchar *command,
-                                                    const gchar *response,
-                                                    gboolean last_command,
-                                                    const GError *error,
-                                                    GVariant **result,
-                                                    GError **result_error)
+mm_base_modem_response_processor_continue_on_error (MMBaseModem   *self,
+                                                    gpointer       none,
+                                                    const gchar   *command,
+                                                    const gchar   *response,
+                                                    gboolean       last_command,
+                                                    const GError  *error,
+                                                    GVariant     **result,
+                                                    GError       **result_error)
 {
     if (error)
+        /* Ignore errors, continue to next command */
         return FALSE;
 
     *result = NULL;
diff --git a/src/mm-base-modem-at.h b/src/mm-base-modem-at.h
index d92a0610..f5f0601e 100644
--- a/src/mm-base-modem-at.h
+++ b/src/mm-base-modem-at.h
@@ -93,42 +93,68 @@ GVariant *mm_base_modem_at_sequence_full_finish (MMBaseModem *self,
 
 /* Common helper response processors */
 
-/* Every string received as response, will be set as result */
-gboolean mm_base_modem_response_processor_string (MMBaseModem *self,
-                                                  gpointer none,
-                                                  const gchar *command,
-                                                  const gchar *response,
-                                                  gboolean last_command,
-                                                  const GError *error,
-                                                  GVariant **result,
-                                                  GError **result_error);
-/* Just abort if error without result set, otherwise finish sequence */
-gboolean mm_base_modem_response_processor_no_result (MMBaseModem *self,
-                                                     gpointer none,
-                                                     const gchar *command,
-                                                     const gchar *response,
-                                                     gboolean last_command,
-                                                     const GError *error,
-                                                     GVariant **result,
-                                                     GError **result_error);
-/* Just abort if error without result set, otherwise continue sequence */
-gboolean mm_base_modem_response_processor_no_result_continue (MMBaseModem *self,
-                                                              gpointer none,
-                                                              const gchar *command,
-                                                              const gchar *response,
-                                                              gboolean last_command,
-                                                              const GError *error,
-                                                              GVariant **result,
-                                                              GError **result_error);
-/* If error, continue sequence, otherwise finish it */
-gboolean mm_base_modem_response_processor_continue_on_error (MMBaseModem *self,
-                                                             gpointer none,
-                                                             const gchar *command,
-                                                             const gchar *response,
-                                                             gboolean last_command,
-                                                             const GError *error,
-                                                             GVariant **result,
-                                                             GError **result_error);
+/*
+ * Response processor for commands that are treated as MANDATORY, where a
+ * failure in the command triggers a failure in the sequence. If successful,
+ * provides the output result as a STRING.
+ */
+gboolean mm_base_modem_response_processor_string (MMBaseModem   *self,
+                                                  gpointer       none,
+                                                  const gchar   *command,
+                                                  const gchar   *response,
+                                                  gboolean       last_command,
+                                                  const GError  *error,
+                                                  GVariant     **result,
+                                                  GError       **result_error);
+
+/*
+ * Response processor for commands that are treated as MANDATORY, where a
+ * failure in the command triggers a failure in the sequence. If successful,
+ * provides the output result as a BOOLEAN.
+ */
+gboolean mm_base_modem_response_processor_no_result (MMBaseModem   *self,
+                                                     gpointer       none,
+                                                     const gchar   *command,
+                                                     const gchar   *response,
+                                                     gboolean       last_command,
+                                                     const GError  *error,
+                                                     GVariant     **result,
+                                                     GError       **result_error);
+
+/*
+ * Response processor for commands that are treated as MANDATORY, where a
+ * failure in the command triggers a failure in the sequence. If successful,
+ * it will run the next command in the sequence.
+ *
+ * E.g. used when we provide a list of commands and we want to run all of
+ * them successfully, and fail the sequence if one of them fails.
+ */
+gboolean mm_base_modem_response_processor_no_result_continue (MMBaseModem   *self,
+                                                              gpointer       none,
+                                                              const gchar   *command,
+                                                              const gchar   *response,
+                                                              gboolean       last_command,
+                                                              const GError  *error,
+                                                              GVariant     **result,
+                                                              GError       **result_error);
+
+/*
+ * Response processor for commands that are treated as OPTIONAL, where a
+ * failure in the command doesn't trigger a failure in the sequence. If
+ * successful, it finishes the sequence.
+ *
+ * E.g. used when we provide a list of commands and we want to stop
+ * as soon as one of them doesn't fail.
+ */
+gboolean mm_base_modem_response_processor_continue_on_error (MMBaseModem   *self,
+                                                             gpointer       none,
+                                                             const gchar   *command,
+                                                             const gchar   *response,
+                                                             gboolean       last_command,
+                                                             const GError  *error,
+                                                             GVariant     **result,
+                                                             GError       **result_error);
+
 
 /* Generic AT command handling, using the best AT port available and without
  * explicit cancellations. */