]> Savannah Git Hosting - gnulib.git/commitdiff
Sync up ProjectQuirks comments and documentation
authorSiddhesh Poyarekar <siddhesh@gotplt.org>
Thu, 20 Aug 2020 03:13:47 +0000 (08:43 +0530)
committerPaul Eggert <eggert@cs.ucla.edu>
Thu, 20 Aug 2020 17:40:20 +0000 (10:40 -0700)
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
doc/vcs-to-changelog.texi

index 6561e387d0360ff0c87ed43dfe303ce13c110d32..ddb34a60552ec0c2fcd74816dba433cfc52f4319 100644 (file)
 
 
 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']
index 683e9606db4dbef283a27edc05c45f10aba8cb86..87f9ae9cd34d056dd86fbaa43255763080b8e3bb 100644 (file)
@@ -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