improve comments

Author: mvorisek

doc/conf.py

@@ -1,16 +1,3 @@
-# -*- coding: utf-8 -*-
-#
-# sphinxcontrib-rubydomain-acceptancetest documentation build configuration file, created by
-# sphinx-quickstart on Sun Apr 25 13:27:18 2010.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
 import sys, os
 
 # If extensions (or modules to document with autodoc) are in another directory,

setup.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 import os
 from setuptools import setup, find_packages
 

sphinxcontrib/__init__.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """
     sphinxcontrib
     ~~~~~~~~~~~~~

sphinxcontrib/phpdomain.py

@@ -1,11 +1,7 @@
-# -*- coding: utf-8 -*-
 """
-    sphinx.domains.php
-    ~~~~~~~~~~~~~~~~~~~
+    Sphinx PHP domain.
 
-    The PHP domain. Based off of the rubydomain by SHIBUKAWA Yoshiki
-
-    :copyright: Copyright 2017 by Mark Story
+    :copyright: Copyright 2023 by Mark Story
     :license: BSD, see LICENSE for details.
 """
 import re
@@ -24,27 +20,34 @@
 from sphinx.util.docfields import Field, GroupedField, TypedField
 from sphinx import __version__ as sphinx_version
 
-# log informative messages
 def log_info(
     fromdocnode,
     message: str
 ):
+    """
+    Log informative message. Should have no affect on exit code.
+    """
     logger = logging.getLogger(__name__)
     logger.info(f"[phpdomain.info] {message}", location=fromdocnode)
 
-# log messages that should fail CI
 def log_warning(
     fromdocnode,
     message: str
 ):
+    """
+    Log warning. Should set exit code to non-zero.
+    """
     logger = logging.getLogger(__name__)
     logger.warning(f"[phpdomain.warning] {message}", location=fromdocnode)
 
-# log assertions that should fail CI
+# 
 def log_assert(
     fromdocnode,
     value: bool
 ):
+    """
+    Log assertion. Should set exit code to non-zero.
+    """
     if not value:
         caller = inspect.getframeinfo(inspect.stack()[1][0])
         logger = logging.getLogger(__name__)
@@ -87,7 +90,8 @@ def log_assert(
 
 def _pseudo_parse_arglist(signode, arglist):
     # type: (addnodes.desc_signature, unicode) -> None
-    """"Parse" a list of arguments separated by commas.
+    """
+    "Parse" a list of arguments separated by commas.
     Arguments can have "optional" annotations given by enclosing them in
     brackets.  Currently, this will split at any comma, even if it's inside a
     string literal (e.g. default argument value).
@@ -640,7 +644,9 @@ def generate(self, docnames=None):
 
 
 class PhpDomain(Domain):
-    """PHP language domain."""
+    """
+    PHP language domain.
+    """
     name = 'php'
     label = 'PHP'
     object_types = {