[PATCH 2/2] [vcs-to-changelog] Sync up ProjectQuirks comments and documentation

[Siddhesh Poyarekar]

Transform the ProjectQuirks comments into a docstring so that it can
be accessed from python as ProjectQuirks.__doc__ and harmonize
descriptions with the documentation.

        * build-aux/vcstocl/projectquirks.py (ProjectQuirks):
        Transform comments into a docstring.
        * doc/vcs-to-changelog.texi: Sync up description with
        comments.
---
 build-aux/vcstocl/projectquirks.py | 39 +++++++++++++++++++-----------
 doc/vcs-to-changelog.texi          | 16 +++++++++---
 2 files changed, 38 insertions(+), 17 deletions(-)

diff --git a/build-aux/vcstocl/projectquirks.py 
b/build-aux/vcstocl/projectquirks.py
index 6561e387d..ddb34a605 100644
--- a/build-aux/vcstocl/projectquirks.py
+++ b/build-aux/vcstocl/projectquirks.py
@@ -16,21 +16,32 @@
 
 
 class ProjectQuirks:
-    # This is a list of regex substitutions for C/C++ macros that are known to
-    # break parsing of the C programs.  Each member of this list is a dict with
-    # the key 'orig' having the regex and 'sub' having the substitution of the
-    # regex.
-    MACRO_QUIRKS = []
+    ''' Base class for project quirks
 
-    # This is a list of macro definitions that are extensively used and are
-    # known to break parsing due to some characteristic, mainly the lack of a
-    # semicolon at the end.
-    C_MACROS = []
+    The following members can be overridden in the subclass:
 
-    # The repo type, defaults to git.
-    repo = 'git'
+    - MACRO_QUIRKS
+      A list of dictionary entries with indexes as `orig` and `sub` where 
`orig`
+      is a Python regular expression pattern to match and `sub` is the
+      substitution.  These substitutions are used to work around C/C++ macros
+      that are known to break parsing of C programs.
+
+    - C_MACROS
+      This is a list of macro definitions that are extensively used and are
+      known to break parsing due to some characteristic, mainly the lack of a
+      semicolon at the end.
+
+    - IGNORE_LIST
+      A list of files to ignore in the changesets, either because they are not
+      needed (such as the ChangeLog) or because they are not parseable.  For
+      example, glibc has a header file that is only assembly code, which breaks
+      the C parser.
 
-    # List of files to ignore either because they are not needed (such as the
-    # ChangeLog) or because they are non-parseable.  For example, glibc has a
-    # header file that is only assembly code, which breaks the C parser.
+    - repo
+      Specify the project repo source control.  The default value is `git`.
+
+    '''
+    MACRO_QUIRKS = []
+    C_MACROS = []
+    repo = 'git'
     IGNORE_LIST = ['ChangeLog']
diff --git a/doc/vcs-to-changelog.texi b/doc/vcs-to-changelog.texi
index 683e9606d..87f9ae9cd 100644
--- a/doc/vcs-to-changelog.texi
+++ b/doc/vcs-to-changelog.texi
@@ -43,9 +43,19 @@ members of @code{ProjectQuirks}:
 @itemize @bullet
 @item @code{repo}: Specify the project repo source control.  The default value
 is @code{git}.
-@item @code{IGNORE_LIST}: A list of files to ignore in the changesets.
+
+@item @code{IGNORE_LIST}: A list of files to ignore in the changesets, either
+because they are not needed (such as the ChangeLog) or because they are
+not parseable.  For example, the GNU C Library has a header file that is only
+assembly code, which breaks the C parser.
+
 @item @code{MACRO_QUIRKS}: A list of dictionary entries with indexes as
 @code{orig} and @code{sub} where @code{orig} is a Python regular expression
-pattern to match and @code{sub} is the substitution.
-@item @code{C_MACROS}: A list of C preprocessor macro definitions.
+pattern to match and @code{sub} is the substitution.  These substitutions are
+used to work around C/C++ macros that are known to break parsing of C programs.
+
+@item @code{C_MACROS}: This is a list of C preprocessor macro definitions that
+are extensively used and are known to break parsing due to some characteristic,
+mainly the lack of a semicolon at the end.
+
 @end itemize
-- 
2.26.2