From 9e73cba3332ca8b9f6364b5c7c7ee65d15441112 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Sun, 3 Aug 2014 00:33:39 +0200 Subject: [PATCH] Improve command documentation. --- qutebrowser/browser/commands.py | 77 ++++++++++++++++-------- qutebrowser/config/config.py | 14 +++++ qutebrowser/keyinput/modeman.py | 6 +- qutebrowser/utils/debug.py | 4 +- qutebrowser/utils/readline.py | 65 ++++++++++++++++---- qutebrowser/widgets/statusbar/command.py | 6 +- 6 files changed, 127 insertions(+), 45 deletions(-) diff --git a/qutebrowser/browser/commands.py b/qutebrowser/browser/commands.py index bf0140ee2..6a7601c85 100644 --- a/qutebrowser/browser/commands.py +++ b/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. - my: How many pages to scroll down. + x: How many pages to scroll to the right. + 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() - dy = int(count) * float(my) * size.height() + dx = int(count) * float(x) * size.width() + 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. - count: If moving absolutely: New position (or first). + direction: + or - for relative moving, none for absolute. + 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. // diff --git a/qutebrowser/config/config.py b/qutebrowser/config/config.py index 0c54fe0c7..9738c9092 100644 --- a/qutebrowser/config/config.py +++ b/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) diff --git a/qutebrowser/keyinput/modeman.py b/qutebrowser/keyinput/modeman.py index ad84fd7dd..1df81754b 100644 --- a/qutebrowser/keyinput/modeman.py +++ b/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. diff --git a/qutebrowser/utils/debug.py b/qutebrowser/utils/debug.py index aaa6d224e..3e24808b6 100644 --- a/qutebrowser/utils/debug.py +++ b/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) diff --git a/qutebrowser/utils/readline.py b/qutebrowser/utils/readline.py index 996ade637..04c59e8e2 100644 --- a/qutebrowser/utils/readline.py +++ b/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() diff --git a/qutebrowser/widgets/statusbar/command.py b/qutebrowser/widgets/statusbar/command.py index 14bb7b27f..9712a8ac0 100644 --- a/qutebrowser/widgets/statusbar/command.py +++ b/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.