Separate docstrings into command/documentation parts.

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: ...
 

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.
 

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.

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:

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
     """

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):

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.

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()