config_parse.py: comment `_ConfigParseErrorCtx` and `_ConfigParseError`

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>

diff --git a/barectf/config_parse.py b/barectf/config_parse.py
index 34ce7b5cf6f6b022b9d41584db1b9aba39c5cc6e..d705c1ffbdddae5f1e6e90aa61cbc4388d7a5945 100644 (file)
--- a/barectf/config_parse.py
+++ b/barectf/config_parse.py
@@ -37,6 +37,9 @@ import re
 import os
 
 
+# The context of a configuration parsing error.
+#
+# Such a context object has a name and, optionally, a message.
 class _ConfigParseErrorCtx:
     def __init__(self, name, msg=None):
         self._name = name
@@ -51,6 +54,24 @@ class _ConfigParseErrorCtx:
         return self._msg
 
 
+# Appends the context having the object name `obj_name` and the
+# (optional) message `msg` to the `_ConfigParseError` exception `exc`
+# and then raises `exc` again.
+def _append_error_ctx(exc, obj_name, msg=None):
+    exc.append_ctx(obj_name, msg)
+    raise
+
+
+# A configuration parsing error.
+#
+# Such an error object contains a list of contexts (`ctx` property).
+#
+# The first context of this list is the most specific context, while the
+# last is the more general.
+#
+# Use append_ctx() to append a context to an existing configuration
+# parsing error when you catch it before raising it again. You can use
+# _append_error_ctx() to do exactly this in a single call.
 class _ConfigParseError(RuntimeError):
     def __init__(self, init_ctx_name, init_ctx_msg=None):
         self._ctx = []
@@ -518,14 +539,6 @@ def _validate_alignment(align, ctx_obj_name):
                                 'Invalid alignment (not a power of two): {}'.format(align))
 
 
-# Appends the context having the object name `obj_name` and the
-# (optional) message `msg` to the `_ConfigParseError` exception `exc`
-# and then raises `exc` again.
-def _append_error_ctx(exc, obj_name, msg=None):
-    exc.append_ctx(obj_name, msg)
-    raise
-
-
 # Entities.
 #
 # Order of values is important here.