From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Fri, 29 May 2020 19:47:55 +0000 (-0400)
Subject: config_parse.py: comment `_ConfigParseErrorCtx` and `_ConfigParseError`
X-Git-Tag: v3.0.0~180
X-Git-Url: http://drtracing.org/?a=commitdiff_plain;h=be7df3b25430d72b25f4a74eea47b1a884518a53;p=barectf.git

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 34ce7b5..d705c1f 100644
--- 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.