Fix formatting and typos in docstrings

linkcheck/__init__.py

@@ -14,7 +14,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 """
-Main function module for link checking.
+Main package for link checking.
 """
 
 # version checks

linkcheck/ansicolor.py

@@ -20,7 +20,7 @@ uses ctypes and Windows DLLs to generate colored output.
 From Term::ANSIColor, applies also to this module:
 
 The codes output by this module are standard terminal control codes,
-complying with ECMA-48 and ISO 6429 (generally referred to as ``ANSI color''
+complying with ECMA-48 and ISO 6429 (generally referred to as "ANSI color"
 for the color codes). The non-color control codes (bold, dark, italic,
 underline, and reverse) are part of the earlier ANSI X3.64 standard for
 control sequences for video terminals and peripherals.

linkcheck/bookmarks/firefox.py

@@ -13,7 +13,7 @@
 # You should have received a copy of the GNU General Public License along
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-"""Parser for FireFox bookmark file."""
+"""Parser for Firefox bookmark file."""
 
 import re
 

linkcheck/checker/__init__.py

@@ -28,10 +28,11 @@ MAX_FILESIZE = 1024 * 1024 * 10  # 10MB
 
 def guess_url(url):
     """Guess if URL is a http or ftp URL.
+
     @param url: the URL to check
-    @ptype url: unicode
+    @type url: unicode
     @return: url with http:// or ftp:// prepended if it's detected as
-      a http respective ftp URL.
+        a http respective ftp URL.
     @rtype: unicode
     """
     if url.lower().startswith("www."):
@@ -90,7 +91,7 @@ def get_url_from(
     @param parent_url: parent url
     @type parent_url: string or None
     @param base_ref: base url from <base> tag
-    @type base_ref string or None
+    @type base_ref: string or None
     @param line: line number
     @type line: number
     @param column: column number

linkcheck/checker/dnsurl.py

@@ -14,7 +14,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 """
-Handle for dns: links.
+Handler for dns: links.
 """
 
 import socket

linkcheck/checker/httpurl.py

@@ -123,9 +123,10 @@ class HttpUrl(internpaturl.InternPatternUrl, proxysupport.ProxySupport):
         The first digit of the Status-Code defines the class of response. The
         last two digits do not have any categorization role. There are 5
         values for the first digit:
+
           - 1xx: Informational - Not used, but reserved for future use
           - 2xx: Success - The action was successfully received,
-            understood, and accepted.
+            understood, and accepted
           - 3xx: Redirection - Further action must be taken in order to
             complete the request
           - 4xx: Client Error - The request contains bad syntax or cannot

linkcheck/checker/mailtourl.py

@@ -14,7 +14,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 """
-Handle for mailto: links.
+Handler for mailto: links.
 """
 
 import re
@@ -136,6 +136,7 @@ class MailtoUrl(urlbase.UrlBase):
 
     def check_email_syntax(self, mail):
         """Check email syntax. The relevant RFCs:
+
         - How to check names (memo):
           https://tools.ietf.org/html/rfc3696
         - Email address syntax

linkcheck/checker/urlbase.py

@@ -61,7 +61,7 @@ def urljoin(parent, url):
     """
     If url is relative, join parent and url. Else leave url as-is.
 
-    @return joined url
+    @return: joined url
     """
     if urlutil.url_is_absolute(url):
         return url
@@ -794,9 +794,9 @@ class UrlBase:
         """Get pattern for intern URL matching.
 
         @param url: the URL to set intern pattern for, else self.url
-        @ptype url: unicode or None
-        @return non-empty regex pattern or None
-        @rtype String or None
+        @type url: unicode or None
+        @return: non-empty regex pattern or None
+        @rtype: String or None
         """
         return None
 
@@ -843,6 +843,7 @@ class UrlBase:
         """Return a simplified transport object for logging and caching.
 
         The transport object must contain these attributes:
+
         - url_data.valid: bool
           Indicates if URL is valid
         - url_data.result: unicode

linkcheck/configuration/__init__.py

@@ -99,10 +99,11 @@ def get_share_dir():
 
 def get_share_file(filename, devel_dir=None):
     """Return a filename in the share directory.
+
     @param devel_dir: directory to search when developing
-    @ptype devel_dir: string
+    @type devel_dir: string
     @param filename: filename to search for
-    @ptype filename: string
+    @type filename: string
     @return: the found filename or None
     @rtype: string
     @raises: ValueError if not found
@@ -135,6 +136,7 @@ def get_system_cert_file():
 
 def get_certifi_file():
     """Get the SSL certifications installed by the certifi package.
+
     @return: the filename to the cert file
     @rtype: string
     @raises: ImportError when certifi is not installed or ValueError when

linkcheck/decorators.py

@@ -16,22 +16,22 @@
 """
 Simple decorators (usable in Python >= 2.4).
 
-Example:
+Example::
 
-@synchronized(thread.allocate_lock())
-def f():
-    "Synchronized function"
-    print("i am synchronized:", f, f.__doc__)
+    @synchronized(thread.allocate_lock())
+    def f():
+        "Synchronized function"
+        print("i am synchronized:", f, f.__doc__)
 
-@deprecated
-def g():
-    "this function is deprecated"
-    pass
+    @deprecated
+    def g():
+        "this function is deprecated"
+        pass
 
-@notimplemented
-def h():
-    "todo"
-    pass
+    @notimplemented
+    def h():
+        "todo"
+        pass
 
 """
 import warnings

linkcheck/director/__init__.py

@@ -27,6 +27,7 @@ from . import aggregator, console
 def check_urls(aggregate):
     """Main check function; checks all configured URLs until interrupted
     with Ctrl-C.
+
     @return: None
     """
     try:

linkcheck/director/interrupt.py

@@ -29,8 +29,9 @@ class Interrupt(task.CheckedTask):
 
     def __init__(self, duration):
         """Initialize the task.
+
         @param duration: raise KeyboardInterrupt after given number of seconds
-        @ptype duration: int
+        @type duration: int
         """
         super().__init__()
         self.duration = duration

linkcheck/director/status.py

@@ -23,12 +23,13 @@ class Status(task.LoggedCheckedTask):
 
     def __init__(self, aggregator, wait_seconds):
         """Initialize the status logger task.
+
         @param urlqueue: the URL queue
-        @ptype urlqueue: Urlqueue
+        @type urlqueue: Urlqueue
         @param logger: the logger object to inform about status
-        @ptype logger: console.StatusLogger
+        @type logger: console.StatusLogger
         @param wait_seconds: interval in seconds to report status
-        @ptype wait_seconds: int
+        @type wait_seconds: int
         """
         logger = aggregator.config.status_logger
         super().__init__(logger)

linkcheck/httputil.py

@@ -51,6 +51,7 @@ def asn1_generaltime_to_seconds(timestr):
     YYYYMMDDhhmmssZ
     YYYYMMDDhhmmss+hhmm
     YYYYMMDDhhmmss-hhmm
+
     @return: a datetime object or None on error
     """
     res = None

linkcheck/lc_cgi.py

@@ -254,8 +254,9 @@ def dump(env, form):
 
 def format_error(why):
     """Format standard error page.
+
     @param why: error message
-    @ptype why: unicode
+    @type why: unicode
     @return: HTML page content
     @rtype: unicode
     """

linkcheck/loader.py

@@ -2,7 +2,8 @@
 """
 Functions to load plugin modules.
 
-Example usage:
+Example usage::
+
     modules = loader.get_package_modules('plugins')
     plugins = loader.get_plugins(modules, PluginClass)
 """
@@ -33,6 +34,7 @@ def get_package_modules(packagename):
     """Find all valid modules in the given package which must be a folder
     in the same directory as this loader.py module. A valid module has
     a .py extension, and is importable.
+
     @return: all loaded valid modules
     @rtype: iterator of module
     """
@@ -75,7 +77,8 @@ def get_folder_modules(folder, parentpackage):
 def get_importable_files(folder):
     """Find all module files in the given folder that end with '.py' and
     don't start with an underscore.
-    @return module names
+
+    @return: module names
     @rtype: iterator of string
     """
     for fname in os.listdir(folder):
@@ -92,10 +95,11 @@ def get_importable_files(folder):
 
 def get_plugins(modules, classes):
     """Find all given (sub-)classes in all modules.
+
     @param modules: the modules to search
-    @ptype modules: iterator of modules
+    @type modules: iterator of modules
     @return: found classes
-    @rytpe: iterator of class objects
+    @rtype: iterator of class objects
     """
     for module in modules:
         for plugin in get_module_plugins(module, classes):

linkcheck/lock.py

@@ -22,8 +22,9 @@ from . import log, LOG_THREAD
 
 def get_lock(name, debug=False):
     """Get a new lock.
+
     @param debug: if True, acquire() and release() will have debug messages
-    @ptype debug: boolean, default is False
+    @type debug: boolean, default is False
     @return: a lock object
     @rtype: threading.Lock or DebugLock
     """
@@ -58,10 +59,11 @@ class DebugLock:
 
 def get_semaphore(name, value=None, debug=False):
     """Get a new semaphore.
+
     @param value: if not None, a BoundedSemaphore will be used
-    @ptype debug: int or None
+    @type debug: int or None
     @param debug: if True, acquire() and release() will have debug messages
-    @ptype debug: boolean, default is False
+    @type debug: boolean, default is False
     @return: a semaphore object
     @rtype: threading.Semaphore or threading.BoundedSemaphore or DebugLock
     """

linkcheck/logger/__init__.py

@@ -446,8 +446,9 @@ class _Logger(abc.ABC):
 
     def format_modified(self, modified, sep=" "):
         """Format modification date in UTC if it's not None.
+
         @param modified: modification date in UTC
-        @ptype modified: datetime or None
+        @type modified: datetime or None
         @return: formatted date or empty string
         @rtype: unicode
         """

linkcheck/memoryutil.py

@@ -29,6 +29,7 @@ MemoryDebugMsg = strformat.format_feature_warning(
 
 def write_memory_dump():
     """Dump memory to a temporary filename with the meliae package.
+
     @return: JSON filename where memory dump has been written to
     @rtype: string
     """

linkcheck/network/iputil.py

@@ -36,8 +36,9 @@ def is_valid_ip(ip):
 
 def resolve_host(host):
     """
-    @host: hostname or IP address
     Return list of ip numbers for given host.
+
+    @param host: hostname or IP address
     """
     ips = []
     try:

linkcheck/plugins/viruscheck.py

@@ -219,8 +219,9 @@ class ClamavConfig(dict):
 
 def scan(data, clamconf):
     """Scan data for viruses.
-    @return (infection msgs, errors)
-    @rtype ([], [])
+
+    @return: (infection msgs, errors)
+    @rtype: ([], [])
     """
     try:
         scanner = ClamdScanner(clamconf)

linkcheck/url.py

@@ -493,9 +493,9 @@ def splitport(host, port=0):
     the given default port is returned.
 
     @param host: host name
-    @ptype host: string
+    @type host: string
     @param port: the port number (default 0)
-    @ptype port: int
+    @type port: int
 
     @return: tuple of (host, port)
     @rtype: tuple of (string, int)