From b6a28aba7b0c8cd23ba5eff88bdb53abb713ca17 Mon Sep 17 00:00:00 2001
From: Florian Bruhin <git@the-compiler.org>
Date: Tue, 4 Mar 2014 07:02:45 +0100
Subject: [PATCH] Add some documentation for decorators

---
 qutebrowser/commands/command.py | 22 +++++++++++++++++++---
 qutebrowser/commands/utils.py   | 26 ++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/qutebrowser/commands/command.py b/qutebrowser/commands/command.py
index d45812387..0e91aaf46 100644
--- a/qutebrowser/commands/command.py
+++ b/qutebrowser/commands/command.py
@@ -29,16 +29,28 @@ class Command(QObject):
     """Base skeleton for a command.
 
     Attributes:
-        FIXME ...
+        name: The main name of the command.
+        split_args: Whether to split the arguments or not.
+        hide: Whether to hide the arguments or not.
+        nargs: A (minargs, maxargs) tuple, maxargs = None if there's no limit.
+        count: Whether the command supports a count, or not.
+        desc: The description of the command.
+        instance: How to get to the "self" argument of the handler.
+                  A dotted string as viewed from app.py, or None.
+        handler: The handler function to call.
+
+    Signals:
+        signal: Gets emitted when something should be called via handle_command
+                from the app.py context.
 
     """
 
-    signal = pyqtSignal(tuple)
-
     # FIXME:
     # we should probably have some kind of typing / argument casting for args
     # this might be combined with help texts or so as well
 
+    signal = pyqtSignal(tuple)
+
     def __init__(self, name, split_args, hide, nargs, count, desc, instance,
                  handler):
         super().__init__()
@@ -76,6 +88,10 @@ class Command(QObject):
             args: Arguments to the command.
             count: Command repetition count.
 
+        Emit:
+            signal: When the command has an instance and should be handled from
+                    the app.py context.
+
         """
         dbgout = ["command called:", self.name]
         if args:
diff --git a/qutebrowser/commands/utils.py b/qutebrowser/commands/utils.py
index 6b3e8e7c5..7cfbaaa0e 100644
--- a/qutebrowser/commands/utils.py
+++ b/qutebrowser/commands/utils.py
@@ -39,12 +39,26 @@ class register:
     This could also be a function, but as a class (with a "wrong" name) it's
     much cleaner to implement.
 
+    Attributes:
+        instance: The instance to be used as "self", as a dotted string.
+        name: The name (as string) or names (as list) of the command.
+        nargs: A (minargs, maxargs) tuple of valid argument counts.
+        split_args: Whether to split the arguments or not.
+        hide: Whether to hide the command or not.
+
     """
 
     # pylint: disable=too-few-public-methods
 
     def __init__(self, instance=None, name=None, nargs=None, split_args=True,
                  hide=False):
+        """Gets called on parse-time with the decorator arguments.
+
+        Arguments:
+            See class attributes.
+
+        """
+
         self.name = name
         self.split_args = split_args
         self.hide = hide
@@ -52,6 +66,18 @@ class register:
         self.instance = instance
 
     def __call__(self, func):
+        """Gets called when a function should be decorated.
+
+        Doesn't actually decorate anything, but creates a Command object and
+        registers it in the cmd_dict.
+
+        Arguments:
+            func: The function to be decorated.
+
+        Return:
+            The original function (unmodified).
+
+        """
         names = []
         name = func.__name__.lower() if self.name is None else self.name
         if isinstance(name, str):