Improve command documentation.

qutebrowser/browser/commands.py

@@ -302,27 +302,43 @@ class CommandDispatcher:
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def prev_page(self):
-        """Open a "previous" link."""
+        """Open a "previous" link.
+
+        This tries to automaticall click on typical "Previous Page" links using
+        some heuristics.
+        """
         self._prevnext(prev=True, newtab=False)
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def next_page(self):
-        """Open a "next" link."""
+        """Open a "next" link.
+
+        This tries to automatically click on typical "Next Page" links using
+        some heuristics.
+        """
         self._prevnext(prev=False, newtab=False)
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def prev_page_tab(self):
-        """Open a "previous" link in a new tab."""
+        """Open a "previous" link in a new tab.
+
+        This tries to automatically click on typical "Previous Page" links using
+        some heuristics.
+        """
         self._prevnext(prev=True, newtab=True)
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def next_page_tab(self):
-        """Open a "next" link in a new tab."""
+        """Open a "next" link in a new tab.
+
+        This tries to automatically click on typical "Previous Page" links using
+        some heuristics.
+        """
         self._prevnext(prev=False, newtab=True)
 
     @cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
     def scroll(self, dx, dy, count=1):
-        """Scroll the current tab by count * dx/dy.
+        """Scroll the current tab by 'count * dx/dy'.
 
         Args:
             dx: How much to scroll in x-direction.
@@ -337,7 +353,10 @@ class CommandDispatcher:
 
     @cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
     def scroll_perc_x(self, perc=None, count=None):
-        """Scroll the current tab to a specific percent of the page (horiz).
+        """Scroll horizontally to a specific percentage of the page.
+
+        The percentage can be given either as argument or as count.
+        If no percentage is given, the page is scrolled to the end.
 
         Args:
             perc: Percentage to scroll.
@@ -347,7 +366,10 @@ class CommandDispatcher:
 
     @cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
     def scroll_perc_y(self, perc=None, count=None):
-        """Scroll the current tab to a specific percent of the page (vert).
+        """Scroll vertically to a specific percentage of the page.
+
+        The percentage can be given either as argument or as count.
+        If no percentage is given, the page is scrolled to the end.
 
         Args:
             perc: Percentage to scroll.
@@ -356,18 +378,18 @@ class CommandDispatcher:
         self._scroll_percent(perc, count, Qt.Vertical)
 
     @cmdutils.register(instance='mainwindow.tabs.cmd', hide=True)
-    def scroll_page(self, mx, my, count=1):
+    def scroll_page(self, x, y, count=1):
         """Scroll the frame page-wise.
 
         Args:
-            mx: How many pages to scroll to the right.
+            x: How many pages to scroll to the right.
-            my: How many pages to scroll down.
+            y: How many pages to scroll down.
             count: multiplier
         """
         frame = self._tabs.currentWidget().page().currentFrame()
         size = frame.geometry()
-        dx = int(count) * float(mx) * size.width()
+        dx = int(count) * float(x) * size.width()
-        dy = int(count) * float(my) * size.height()
+        dy = int(count) * float(y) * size.height()
         cmdutils.check_overflow(dx, 'int')
         cmdutils.check_overflow(dy, 'int')
         frame.scroll(dx, dy)
@@ -417,7 +439,7 @@ class CommandDispatcher:
         """Increase the zoom level for the current tab.
 
         Args:
-            count: How many steps to take.
+            count: How many steps to zoom in.
         """
         tab = self._tabs.currentWidget()
         tab.zoom(count)
@@ -427,17 +449,21 @@ class CommandDispatcher:
         """Decrease the zoom level for the current tab.
 
         Args:
-            count: How many steps to take.
+            count: How many steps to zoom out.
         """
         tab = self._tabs.currentWidget()
         tab.zoom(-count)
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def zoom(self, zoom=None, count=None):
-        """Set the zoom level for the current tab to [count] or 100 percent.
+        """Set the zoom level for the current tab.
+
+        The zoom can be given as argument or as [count]. If neither of both is
+        given, the zoom is set to 100%.
 
         Args:
-            count: How many steps to take.
+            zoom: The zoom percentage to set.
+            count: The zoom percentage to set.
         """
         try:
             level = cmdutils.arg_or_count(zoom, count, default=100)
@@ -474,7 +500,7 @@ class CommandDispatcher:
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def undo(self):
-        """Re-open a closed tab (optionally skipping [count] tabs)."""
+        """Re-open a closed tab (optionally skipping [count] closed tabs)."""
         if self._tabs.url_stack:
             self._tabs.tabopen(self._tabs.url_stack.pop())
         else:
@@ -482,7 +508,7 @@ class CommandDispatcher:
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def tab_prev(self, count=1):
-        """Switch to the previous tab, or skip [count] tabs.
+        """Switch to the previous tab, or switch [count] tabs back.
 
         Args:
             count: How many tabs to switch back.
@@ -497,7 +523,7 @@ class CommandDispatcher:
 
     @cmdutils.register(instance='mainwindow.tabs.cmd')
     def tab_next(self, count=1):
-        """Switch to the next tab, or skip [count] tabs.
+        """Switch to the next tab, or switch [count] tabs forward.
 
         Args:
             count: How many tabs to switch forward.
@@ -548,6 +574,7 @@ class CommandDispatcher:
 
         Args:
             index: The tab index to focus, starting with 1.
+            count: The tab index to focus, starting with 1.
         """
         try:
             idx = cmdutils.arg_or_count(index, count, default=1,
@@ -565,8 +592,8 @@ class CommandDispatcher:
         """Move the current tab.
 
         Args:
-            direction: + or - for relative moving, None for absolute.
+            direction: + or - for relative moving, none for absolute.
-            count: If moving absolutely: New position (or first).
+            count: If moving absolutely: New position (default: 0)
                    If moving relatively: Offset.
         """
         if direction is None:
@@ -614,7 +641,7 @@ class CommandDispatcher:
         don't care about the process anymore as soon as it's spawned.
 
         Args:
-            *args: The commandline to execute
+            *args: The commandline to execute.
         """
         log.procs.debug("Executing: {}".format(args))
         subprocess.Popen(args)
@@ -631,7 +658,6 @@ class CommandDispatcher:
         Args:
             cmd: The userscript to run.
             args: Arguments to pass to the userscript.
-            url: A custom QUrl to use instead of the current url.
         """
         url = self._tabs.current_url()
         userscripts.run(cmd, *args, url=url)
@@ -692,7 +718,10 @@ class CommandDispatcher:
     @cmdutils.register(instance='mainwindow.tabs.cmd', modes=[KeyMode.insert],
                        hide=True)
     def open_editor(self):
-        """Open an external editor with the current form field.
+        """Open an external editor with the currently selected form field.
+
+        The editor which should be launched can be configured via the
+        `general -> editor` config option.
 
         //
 

qutebrowser/config/config.py

@@ -291,6 +291,10 @@ class ConfigManager(QObject):
         //
 
         Wrapper for the get-command to output the value in the status bar.
+
+        Args:
+            sectname: The section where the option is in.
+            optname: The name of the option.
         """
         try:
             val = self.get(sectname, optname, transformed=False)
@@ -338,6 +342,11 @@ class ConfigManager(QObject):
         //
 
         Wrapper for self.set() to output exceptions in the status bar.
+
+        Args:
+            sectname: The section where the option is in.
+            optname: The name of the option.
+            value: The value to set.
         """
         try:
             self.set('conf', sectname, optname, value)
@@ -354,6 +363,11 @@ class ConfigManager(QObject):
         //
 
         Wrapper for self.set() to output exceptions in the status bar.
+
+        Args:
+            sectname: The section where the option is in.
+            optname: The name of the option.
+            value: The value to set.
         """
         try:
             self.set('temp', sectname, optname, value)

qutebrowser/keyinput/modeman.py

@@ -213,10 +213,10 @@ class ModeManager(QObject):
 
     @cmdutils.register(instance='modeman', hide=True)
     def enter_mode(self, mode):
-        """Enter mode as a command.
+        """Enter a key mode.
 
         Args:
-            mode: The mode to enter as a string.
+            mode: The mode to enter.
         """
         try:
             m = KeyMode[mode]
@@ -225,7 +225,7 @@ class ModeManager(QObject):
         self.enter(m, 'command')
 
     def leave(self, mode, reason=None):
-        """Leave a mode.
+        """Leave a key mode.
 
         Args:
             mode: The name of the mode to leave.

qutebrowser/utils/debug.py

@@ -55,7 +55,7 @@ def debug_crash(typ='exception'):
     """Crash for debugging purposes.
 
     Args:
-        typ: either 'exception' or 'segfault'
+        typ: either 'exception' or 'segfault'.
 
     Raises:
         raises Exception when typ is not segfault.
@@ -80,7 +80,7 @@ def debug_all_widgets():
 
 @cmdutils.register(debug=True)
 def debug_all_objects():
-    """Dump all children of an object recursively."""
+    """Print a list of  all objects to the debug log."""
     s = QCoreApplication.instance().get_all_objects()
     logger.debug(s)
 

qutebrowser/utils/readline.py

@@ -48,7 +48,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_backward_char(self):
-        """Readline: Move back a character."""
+        """Move back a character.
+
+        This acts like readline's backward-char.
+        """
         if self.widget is None:
             return
         self.widget.cursorBackward(False)
@@ -56,7 +59,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_forward_char(self):
-        """Readline: Move forward a character."""
+        """Move forward a character.
+
+        This acts like readline's forward-char.
+        """
         if self.widget is None:
             return
         self.widget.cursorForward(False)
@@ -64,7 +70,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_backward_word(self):
-        """Readline: Move back to the start of the current or previous word."""
+        """Move back to the start of the current or previous word.
+
+        This acts like readline's backward-word.
+        """
         if self.widget is None:
             return
         self.widget.cursorWordBackward(False)
@@ -72,7 +81,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_forward_word(self):
-        """Readline: Move forward to the end of the next word."""
+        """Move forward to the end of the next word.
+
+        This acts like readline's forward-word.
+        """
         if self.widget is None:
             return
         self.widget.cursorWordForward(False)
@@ -80,7 +92,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_beginning_of_line(self):
-        """Readline: Move to the start of the current line."""
+        """Move to the start of the line.
+
+        This acts like readline's beginning-of-line.
+        """
         if self.widget is None:
             return
         self.widget.home(False)
@@ -88,7 +103,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_end_of_line(self):
-        """Readline: Move to the end of the line."""
+        """Move to the end of the line.
+
+        This acts like readline's end-of-line.
+        """
         if self.widget is None:
             return
         self.widget.end(False)
@@ -96,7 +114,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_unix_line_discard(self):
-        """Readline: Kill backward from cursor to the beginning of the line."""
+        """Remove chars backward from the cursor to the beginning of the line.
+
+        This acts like readline's unix-line-discard.
+        """
         if self.widget is None:
             return
         self.widget.home(True)
@@ -106,7 +127,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_kill_line(self):
-        """Readline: Kill the text from point to the end of the line."""
+        """Remove chars from the cursor to the end of the line.
+
+        This acts like readline's kill-line.
+        """
         if self.widget is None:
             return
         self.widget.end(True)
@@ -116,7 +140,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_unix_word_rubout(self):
-        """Readline: Kill the word behind point."""
+        """Remove chars from the cursor to the beginning of the word.
+
+        This acts like readline's unix-word-rubout.
+        """
         if self.widget is None:
             return
         self.widget.cursorWordBackward(True)
@@ -126,7 +153,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_kill_word(self):
-        """Readline: Kill from point to the end of the current word."""
+        """Remove chars from the cursor to the end of the current word.
+
+        This acts like readline's kill-word.
+        """
         if self.widget is None:
             return
         self.widget.cursorWordForward(True)
@@ -136,7 +166,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_yank(self):
-        """Readline: Yank the top of the kill ring into the buffer at point."""
+        """Paste the most recently deleted text.
+
+        This acts like readline's yank.
+        """
         if self.widget is None or self.widget not in self.deleted:
             return
         self.widget.insert(self.deleted[self.widget])
@@ -144,7 +177,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_delete_char(self):
-        """Readline: Delete the character at point."""
+        """Delete the character after the cursor.
+
+        This acts like readline's delete-char.
+        """
         if self.widget is None:
             return
         self.widget.del_()
@@ -152,7 +188,10 @@ class ReadlineBridge:
     @cmd.register(instance='rl_bridge', hide=True,
                   modes=[KeyMode.command, KeyMode.prompt])
     def rl_backward_delete_char(self):
-        """Readline: Delete the character behind the cursor."""
+        """Delete the character before the cursor.
+
+        This acts like readline's backward-delete-char.
+        """
         if self.widget is None:
             return
         self.widget.backspace()

qutebrowser/widgets/statusbar/command.py

@@ -221,7 +221,7 @@ class Command(MinimalLineEdit):
     @cmdutils.register(instance='mainwindow.status.cmd', hide=True,
                        modes=[KeyMode.command])
     def command_history_prev(self):
-        """Handle Up presses (go back in history)."""
+        """Go back in the commandline history."""
         try:
             if not self.history.browsing:
                 item = self.history.start(self.text().strip())
@@ -235,7 +235,7 @@ class Command(MinimalLineEdit):
     @cmdutils.register(instance='mainwindow.status.cmd', hide=True,
                        modes=[KeyMode.command])
     def command_history_next(self):
-        """Handle Down presses (go forward in history)."""
+        """Go forward in the commandline history."""
         if not self.history.browsing:
             return
         try:
@@ -248,7 +248,7 @@ class Command(MinimalLineEdit):
     @cmdutils.register(instance='mainwindow.status.cmd', hide=True,
                        modes=[KeyMode.command])
     def command_accept(self):
-        """Handle the command in the status bar.
+        """Execute the command currently in the commandline.
 
         Emit:
             got_cmd: If a new cmd was entered.