[gi-docgen/check-ignore: 2/6] check: Allow ignoring symbols

[Emmanuele Bassi <ebassi src gnome org>]

commit 5d78e80d9ab92e580efef0aa5264cae82d1cfda4
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri Jun 11 13:36:57 2021 +0100

    check: Allow ignoring symbols
    
    Some symbols are documented, but we know they are not going to pass the
    "check" conditions.

 docs/project-configuration.rst |  25 +++++++--
 gidocgen/gdcheck.py            | 120 +++++++++++++++++++++++++++++++++++------
 2 files changed, 126 insertions(+), 19 deletions(-)
---
diff --git a/docs/project-configuration.rst b/docs/project-configuration.rst
index cda882e..9206b3b 100644
--- a/docs/project-configuration.rst
+++ b/docs/project-configuration.rst
@@ -185,7 +185,15 @@ The ``object`` key is always an array of dictionaries; each element in the array
 can have a ``name`` key, used to match the object name exactly; or a ``pattern``
 key, which uses a regular expression to match the object name.
 
-Each element can also have the following keys:
+Each object can contain the following keys:
+
+ - ``name``: the name of the symbol to match exactly
+ - ``pattern``: a regular expression to match the symbol name
+ - ``hidden``: whether the symbol should be hidden from the documentation
+ - ``check_ignore``: whether the symbol should be skipped when checking the
+   documentation
+
+Each element can also have the following sections:
 
  - ``property``
  - ``signal``
@@ -193,8 +201,7 @@ Each element can also have the following keys:
  - ``method``
  - ``function``
 
-Each one of these keys can contain array of dictionaries with a ``name`` or
-``pattern`` keys, and a ``hidden`` key.
+Each one of these sections can contain array of objects.
 
 The following example will hide the ``backend`` property on the ``Printer`` type:
 
@@ -218,3 +225,15 @@ The following example will hide the ``private-changed`` signal on the
       [[object.signal]]
       name = "private-changed"
       hidden = true
+
+The following example will skip the ``quark`` function on the ``ParserError``
+type when checking the documentation:
+
+::
+
+    [[object]]
+    name = "ParserError"
+
+      [[object.function]]
+      name = "quark"
+      check_ignore = true
diff --git a/gidocgen/gdcheck.py b/gidocgen/gdcheck.py
index 0a5fce7..bb28c9f 100644
--- a/gidocgen/gdcheck.py
+++ b/gidocgen/gdcheck.py
@@ -4,7 +4,7 @@
 import argparse
 import sys
 
-from . import gir, log, utils
+from . import config, gir, log, utils
 
 
 HELP_MSG = "Checks introspection data for valid documentation"
@@ -43,168 +43,251 @@ def _check_retval_docs(path, retval, results):
         results.append(f"Return value for symbol '{symbol}' is not documented")
 
 
-def _check_aliases(repository, symbols, results):
+def _check_aliases(config, repository, symbols, results):
     for alias in symbols:
+        if config.is_skipped(alias.name):
+            log.debug(f"Skipping hidden alias {alias.name}")
+            continue
         _check_doc_element([repository.namespace.name], alias, results)
 
 
-def _check_bitfields(repository, symbols, results):
+def _check_bitfields(config, repository, symbols, results):
     for bitfield in symbols:
+        if config.is_skipped(bitfield.name):
+            log.debug(f"Skipping hidden bitfield {bitfield.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], bitfield, results)
 
         for member in bitfield.members:
             _check_doc_element([repository.namespace.name, bitfield.name], member, results)
 
         for func in bitfield.functions:
+            if config.is_skipped(bitfield.name, 'function', func.name):
+                continue
             _check_doc_element([repository.namespace.name, bitfield.name], func, results)
             _check_arg_docs([repository.namespace.name, bitfield.name, func.name], func.parameters, results)
             _check_retval_docs([repository.namespace.name, bitfield.name, func.name], func.return_value, 
results)
 
 
-def _check_callbacks(repository, symbols, results):
+def _check_callbacks(config, repository, symbols, results):
     for cb in symbols:
+        if config.is_skipped(cb.name):
+            log.debug(f"Skipping hidden callback {cb.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], cb, results)
         _check_arg_docs([repository.namespace.name, cb.name], cb.parameters, results)
         _check_retval_docs([repository.namespace.name, cb.name], cb.return_value, results)
 
 
-def _check_classes(repository, symbols, results):
+def _check_classes(config, repository, symbols, results):
     for cls in symbols:
+        if config.is_skipped(cls.name):
+            log.debug(f"Skipping hidden class {cls.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], cls, results)
 
         for ctor in cls.constructors:
+            if config.is_skipped(cls.name, 'constructor', ctor.name):
+                continue
             _check_doc_element([repository.namespace.name, cls.name], ctor, results)
             _check_arg_docs([repository.namespace.name, cls.name, ctor.name], ctor.parameters, results)
             _check_retval_docs([repository.namespace.name, cls.name, ctor.name], ctor.return_value, results)
 
         for method in cls.methods:
+            if config.is_skipped(cls.name, 'method', method.name):
+                continue
             _check_doc_element([repository.namespace.name, cls.name], method, results)
             _check_arg_docs([repository.namespace.name, cls.name, method.name], method.parameters, results)
             _check_retval_docs([repository.namespace.name, cls.name, method.name], method.return_value, 
results)
 
         for func in cls.functions:
+            if config.is_skipped(cls.name, 'function', func.name):
+                continue
             _check_doc_element([repository.namespace.name, cls.name], func, results)
             _check_arg_docs([repository.namespace.name, cls.name, func.name], func.parameters, results)
             _check_retval_docs([repository.namespace.name, cls.name, func.name], func.return_value, results)
 
         for prop in cls.properties.values():
+            if config.is_skipped(cls.name, 'property', prop.name):
+                continue
             _check_doc_element([repository.namespace.name, cls.name], prop, results)
 
         for signal in cls.signals.values():
+            if config.is_skipped(cls.name, 'signal', signal.name):
+                continue
             _check_doc_element([repository.namespace.name, cls.name], signal, results)
             _check_arg_docs([repository.namespace.name, cls.name, signal.name], signal.parameters, results)
             _check_retval_docs([repository.namespace.name, cls.name, signal.name], signal.return_value, 
results)
 
 
-def _check_constants(repository, symbols, results):
+def _check_constants(config, repository, symbols, results):
     for constant in symbols:
+        if config.is_skipped(constant.name):
+            log.debug(f"Skipping hidden constant {constant.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], constant, results)
 
 
-def _check_domains(repository, symbols, results):
+def _check_domains(config, repository, symbols, results):
     for domain in symbols:
+        if config.is_skipped(domain.name):
+            log.debug(f"Skipping hidden error domain {domain.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], domain, results)
 
         for member in domain.members:
             _check_doc_element([repository.namespace.name, domain.name], member, results)
 
         for func in domain.functions:
+            if config.is_skipped(domain.name, 'function', func.name):
+                continue
             _check_doc_element([repository.namespace.name, domain.name], func, results)
             _check_arg_docs([repository.namespace.name, domain.name, func.name], func.parameters, results)
             _check_retval_docs([repository.namespace.name, domain.name, func.name], func.return_value, 
results)
 
 
-def _check_enums(repository, symbols, results):
+def _check_enums(config, repository, symbols, results):
     for enum in symbols:
+        if config.is_skipped(enum.name):
+            log.debug(f"Skipping hidden enumeration {enum.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], enum, results)
 
         for member in enum.members:
             _check_doc_element([repository.namespace.name, enum.name], member, results)
 
         for func in enum.functions:
+            if config.is_skipped(enum.name, 'function', func.name):
+                continue
             _check_doc_element([repository.namespace.name, enum.name], func, results)
             _check_arg_docs([repository.namespace.name, enum.name, func.name], func.parameters, results)
             _check_retval_docs([repository.namespace.name, enum.name, func.name], func.return_value, results)
 
 
-def _check_functions(repository, symbols, results):
+def _check_functions(config, repository, symbols, results):
     for func in symbols:
+        if config.is_skipped(func.name):
+            log.debug(f"Skipping hidden function {func.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], func, results)
         _check_arg_docs([repository.namespace.name, func.name], func.parameters, results)
         _check_retval_docs([repository.namespace.name, func.name], func.return_value, results)
 
 
-def _check_function_macros(repository, symbols, results):
+def _check_function_macros(config, repository, symbols, results):
     for func in symbols:
+        if config.is_skipped(func.name):
+            log.debug(f"Skipping hidden function macro {func.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], func, results)
         _check_arg_docs([repository.namespace.name, func.name], func.parameters, results)
         _check_retval_docs([repository.namespace.name, func.name], func.return_value, results)
 
 
-def _check_interfaces(repository, symbols, results):
+def _check_interfaces(config, repository, symbols, results):
     for iface in symbols:
+        if config.is_skipped(iface.name):
+            log.debug(f"Skipping hidden interface {iface.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], iface, results)
 
         for method in iface.methods:
+            if config.is_skipped(iface.name, 'method', method.name):
+                continue
             _check_doc_element([repository.namespace.name, iface.name], method, results)
             _check_arg_docs([repository.namespace.name, iface.name, method.name], method.parameters, results)
             _check_retval_docs([repository.namespace.name, iface.name, method.name], method.return_value, 
results)
 
         for func in iface.functions:
+            if config.is_skipped(iface.name, 'function', func.name):
+                continue
             _check_doc_element([repository.namespace.name, iface.name], func, results)
             _check_arg_docs([repository.namespace.name, iface.name, func.name], func.parameters, results)
             _check_retval_docs([repository.namespace.name, iface.name, func.name], func.return_value, 
results)
 
         for prop in iface.properties.values():
+            if config.is_skipped(iface.name, 'property', prop.name):
+                continue
             _check_doc_element([repository.namespace.name, iface.name], prop, results)
 
         for signal in iface.signals.values():
+            if config.is_skipped(iface.name, 'signal', signal.name):
+                continue
             _check_doc_element([repository.namespace.name, iface.name], signal, results)
             _check_arg_docs([repository.namespace.name, iface.name, signal.name], signal.parameters, results)
             _check_retval_docs([repository.namespace.name, iface.name, signal.name], signal.return_value, 
results)
 
 
-def _check_records(repository, symbols, results):
+def _check_records(config, repository, symbols, results):
     for struct in symbols:
+        if config.is_skipped(struct.name):
+            log.debug(f"Skipping hidden record {struct.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], struct, results)
 
         for ctor in struct.constructors:
+            if config.is_skipped(struct.name, 'constructor', ctor.name):
+                continue
             _check_doc_element([repository.namespace.name, struct.name], ctor, results)
             _check_arg_docs([repository.namespace.name, struct.name, ctor.name], ctor.parameters, results)
             _check_retval_docs([repository.namespace.name, struct.name, ctor.name], ctor.return_value, 
results)
 
         for method in struct.methods:
+            if config.is_skipped(struct.name, 'method', method.name):
+                continue
             _check_doc_element([repository.namespace.name, struct.name], method, results)
             _check_arg_docs([repository.namespace.name, struct.name, method.name], method.parameters, 
results)
             _check_retval_docs([repository.namespace.name, struct.name, method.name], method.return_value, 
results)
 
         for func in struct.functions:
+            if config.is_skipped(struct.name, 'function', func.name):
+                continue
             _check_doc_element([repository.namespace.name, struct.name], func, results)
             _check_arg_docs([repository.namespace.name, struct.name, func.name], func.parameters, results)
             _check_retval_docs([repository.namespace.name, struct.name, func.name], func.return_value, 
results)
 
 
-def _check_unions(repository, symbols, results):
+def _check_unions(config, repository, symbols, results):
     for union in symbols:
+        if config.is_skipped(union.name):
+            log.debug(f"Skipping hidden union {union.name}")
+            continue
+
         _check_doc_element([repository.namespace.name], union, results)
 
         for ctor in union.constructors:
+            if config.is_skipped(union.name, 'constructor', ctor.name):
+                continue
             _check_doc_element([repository.namespace.name, union.name], ctor, results)
             _check_arg_docs([repository.namespace.name, union.name, ctor.name], ctor.parameters, results)
             _check_retval_docs([repository.namespace.name, union.name, ctor.name], ctor.return_value, 
results)
 
         for method in union.methods:
+            if config.is_skipped(union.name, 'method', method.name):
+                continue
             _check_doc_element([repository.namespace.name, union.name], method, results)
             _check_arg_docs([repository.namespace.name, union.name, method.name], method.parameters, results)
             _check_retval_docs([repository.namespace.name, union.name, method.name], method.return_value, 
results)
 
         for func in union.functions:
+            if config.is_skipped(union.name, 'function', func.name):
+                continue
             _check_doc_element([repository.namespace.name, union.name], func, results)
             _check_arg_docs([repository.namespace.name, union.name, func.name], func.parameters, results)
             _check_retval_docs([repository.namespace.name, union.name, func.name], func.return_value, 
results)
 
 
-def check(repository):
+def check(repository, config):
     namespace = repository.namespace
 
     symbols = {
@@ -252,7 +335,7 @@ def check(repository):
             continue
 
         log.debug(f"Checking symbols for section {section}")
-        checker(repository, s, results)
+        checker(config, repository, s, results)
 
     for res in results:
         log.warning(res)
@@ -261,6 +344,7 @@ def check(repository):
 
 
 def add_args(parser):
+    parser.add_argument("-C", "--config", metavar="FILE", help="the configuration file")
     parser.add_argument("--add-include-path", action="append", dest="include_paths", default=[],
                         help="include paths for other GIR files")
     parser.add_argument("infile", metavar="GIRFILE", type=argparse.FileType('r', encoding='UTF-8'),
@@ -268,6 +352,10 @@ def add_args(parser):
 
 
 def run(options):
+    log.info(f"Loading config file: {options.config}")
+
+    conf = config.GIDocConfig(options.config)
+
     paths = []
     paths.extend(options.include_paths)
     paths.extend(utils.default_search_paths())
@@ -277,4 +365,4 @@ def run(options):
     parser.parse(options.infile)
 
     log.checkpoint()
-    return check(parser.get_repository())
+    return check(parser.get_repository(), conf)