From f7304298abdad53a257ba7eb53f30326fd514200 Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Wed, 16 Jul 2014 20:09:41 +0200 Subject: [PATCH] Separate docstrings into command/documentation parts. --- doc/HACKING.asciidoc | 11 +++++++++++ qutebrowser/app.py | 2 ++ qutebrowser/browser/commands.py | 4 ++++ qutebrowser/config/config.py | 6 ++++++ qutebrowser/utils/debug.py | 4 +++- qutebrowser/widgets/mainwindow.py | 7 ++++++- qutebrowser/widgets/statusbar/prompter.py | 4 +++- scripts/generate_manpage.py | 15 ++++++++++++++- 8 files changed, 49 insertions(+), 4 deletions(-) diff --git a/doc/HACKING.asciidoc b/doc/HACKING.asciidoc index 4d1df37d2..374907bc6 100644 --- a/doc/HACKING.asciidoc +++ b/doc/HACKING.asciidoc @@ -346,6 +346,11 @@ http://legacy.python.org/dev/peps/pep-0008/[PEP8] and the https://google-stylegu http://legacy.python.org/dev/peps/pep-0257/[PEP257] and the google guidelines. * Class docstrings have additional _Attributes:_, _Class attributes:_ and _Signals:_ sections, method/function docstrings have an _Emit:_ section. +* In docstrings of command handlers (registered via `@cmdutils.register`), the +description should be split into two parts by using `//` - the first part is +the description of the command like it will appear in the documentation, the +second part is "internal" documentation only relevant to people reading the +sourcecode. + Example for a class docstring: + @@ -368,6 +373,12 @@ Example for a method/function docstring: ---- """Do something special. +This will do something. + +// + +It is based on http://example.com/. + Args: foo: ... diff --git a/qutebrowser/app.py b/qutebrowser/app.py index d61a1f087..4827b76a9 100644 --- a/qutebrowser/app.py +++ b/qutebrowser/app.py @@ -616,6 +616,8 @@ class Application(QApplication): def debug_pyeval(self, s): """Evaluate a python string and display the results as a webpage. + // + We have this here rather in utils.debug so the context of eval makes more sense and because we don't want to import much stuff in the utils. diff --git a/qutebrowser/browser/commands.py b/qutebrowser/browser/commands.py index b856b7717..e0d8690f3 100644 --- a/qutebrowser/browser/commands.py +++ b/qutebrowser/browser/commands.py @@ -619,6 +619,8 @@ class CommandDispatcher: The command will be run in a shell, so you can use shell features like redirections. + // + We use subprocess rather than Qt's QProcess here because of it's shell=True argument and because we really don't care about the process anymore as soon as it's spawned. @@ -706,6 +708,8 @@ class CommandDispatcher: def open_editor(self): """Open an external editor with the current form field. + // + We use QProcess rather than subprocess here because it makes it a lot easier to execute some code as soon as the process has been finished and do everything async. diff --git a/qutebrowser/config/config.py b/qutebrowser/config/config.py index f92acb134..0568e3791 100644 --- a/qutebrowser/config/config.py +++ b/qutebrowser/config/config.py @@ -287,6 +287,8 @@ class ConfigManager(QObject): def get_wrapper(self, sectname, optname): """Get the value from a section/option. + // + Wrapper for the get-command to output the value in the status bar. """ try: @@ -331,6 +333,8 @@ class ConfigManager(QObject): def set_wrapper(self, sectname, optname, value): """Set an option. + // + Wrapper for self.set() to output exceptions in the status bar. """ try: @@ -344,6 +348,8 @@ class ConfigManager(QObject): def set_temp_wrapper(self, sectname, optname, value): """Set a temporary option. + // + Wrapper for self.set() to output exceptions in the status bar. """ try: diff --git a/qutebrowser/utils/debug.py b/qutebrowser/utils/debug.py index c8b3f443a..e9d998e3f 100644 --- a/qutebrowser/utils/debug.py +++ b/qutebrowser/utils/debug.py @@ -34,7 +34,9 @@ import qutebrowser.commands.utils as cmdutils @cmdutils.register(debug=True, name='debug-set-trace') def set_trace(): - """Set a tracepoint in the Python debugger that works with Qt. + """Break into the debugger in the shell. + + // Based on http://stackoverflow.com/a/1745965/2085149 """ diff --git a/qutebrowser/widgets/mainwindow.py b/qutebrowser/widgets/mainwindow.py index 09d47bb5f..173c408bd 100644 --- a/qutebrowser/widgets/mainwindow.py +++ b/qutebrowser/widgets/mainwindow.py @@ -148,7 +148,12 @@ class MainWindow(QWidget): @cmdutils.register(instance='mainwindow', name=['quit', 'q'], nargs=0) def close(self): - """Extend close() so we can register it as a command.""" + """Quit qutebrowser. + + // + + Extend close() so we can register it as a command. + """ super().close() def resizeEvent(self, e): diff --git a/qutebrowser/widgets/statusbar/prompter.py b/qutebrowser/widgets/statusbar/prompter.py index 7250c4aac..b4b63b49f 100644 --- a/qutebrowser/widgets/statusbar/prompter.py +++ b/qutebrowser/widgets/statusbar/prompter.py @@ -171,7 +171,9 @@ class Prompter: @cmdutils.register(instance='mainwindow.status.prompt.prompter', hide=True, modes=['prompt']) def prompt_accept(self): - """Accept the prompt. + """Accept the current prompt. + + // This executes the next action depending on the question mode, e.g. asks for the password or leaves the mode. diff --git a/scripts/generate_manpage.py b/scripts/generate_manpage.py index 5599c69e6..e8ccb4803 100644 --- a/scripts/generate_manpage.py +++ b/scripts/generate_manpage.py @@ -41,7 +41,8 @@ def parse_docstring(func): Return: A (short_desc, long_desc, arg_descs) tuple. """ - State = enum('short', 'desc', 'arg_start', 'arg_inside') + State = enum('short', 'desc', 'desc_hidden', 'arg_start', 'arg_inside', + 'misc') doc = inspect.getdoc(func) lines = doc.splitlines() @@ -61,8 +62,20 @@ def parse_docstring(func): elif cur_state == State.desc: if line.startswith('Args:'): cur_state = State.arg_start + elif line.startswith('Emit:') or line.startswith('Raise:'): + cur_state = State.misc + elif line.strip() == '//': + cur_state = State.desc_hidden elif line.strip(): long_desc.append(line.strip()) + elif cur_state == State.misc: + if line.startswith('Args:'): + cur_state = State.arg_start + else: + pass + elif cur_state == State.desc_hidden: + if line.startswith('Args:'): + cur_state = State.arg_start elif cur_state == State.arg_start: cur_arg_name, argdesc = line.split(':', maxsplit=1) cur_arg_name = cur_arg_name.strip()