Remove Emit:/Raise: from docstrings.

They got out-of-sync fast and provided no real benefit.

doc/HACKING.asciidoc

@@ -431,12 +431,13 @@ Style conventions
 qutebrowser's coding conventions are based on
 http://legacy.python.org/dev/peps/pep-0008/[PEP8] and the https://google-styleguide.googlecode.com/svn/trunk/pyguide.html[Google Python style guidelines] with some additions:
 
+* The _Raise:_ section is not added to the docstring.
 * Methods overriding Qt methods (obviously!) don't follow the naming schemes.
 * Everything else does though, even slots.
 * Docstrings should look like described in
 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.
+  _Signals:_ sections.
 * 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
@@ -475,12 +476,6 @@ Args:
 
 Return:
     True if something, False if something else.
-
-Raise:
-    ValueError if foo is None
-
-Emit:
-    value_changed
 """
 ----
 +

qutebrowser/browser/signalfilter.py

@@ -75,9 +75,6 @@ class SignalFilter(QObject):
             signal: The signal to emit if the sender was the current widget.
             tab: The WebView which the filter belongs to.
             *args: The args to pass to the signal.
-
-        Emit:
-            The target signal if the sender was the current widget.
         """
         log_signal = debug.signal_name(signal) not in self.BLACKLIST
         tabbed_browser = objreg.get('tabbed-browser', scope='window',

qutebrowser/browser/webpage.py

@@ -166,12 +166,7 @@ class BrowserPage(QWebPage):
 
     @pyqtSlot('QNetworkRequest')
     def on_download_requested(self, request):
-        """Called when the user wants to download a link.
+        """Called when the user wants to download a link."""
-
-        Emit:
-            start_download: Emitted with the QNetworkReply associated with the
-                            passed request.
-        """
         reply = self.networkAccessManager().get(request)
         self.start_download.emit(reply)
 

qutebrowser/commands/cmdutils.py

@@ -36,10 +36,6 @@ def check_overflow(arg, ctype):
     Args:
         arg: The argument to check
         ctype: The C/Qt type to check as a string.
-
-    Raise:
-        CommandError if the argument is out of bounds.
-        ValueError if the given ctype is unknown.
     """
     try:
         qtutils.check_overflow(arg, ctype)
@@ -63,9 +59,6 @@ def arg_or_count(arg, count, default=None, countzero=None):
 
     Return:
         The value to use.
-
-    Raise:
-        ValueError: If nothing was set.
     """
     if count is not None and arg is not None:
         raise ValueError("Both count and argument given!")

qutebrowser/commands/command.py

@@ -100,9 +100,6 @@ class Command:
 
         Args:
             win_id: The window ID the command is run in.
-
-        Raise:
-            PrerequisitesError if the command can't be called currently.
         """
         mode_manager = objreg.get('mode-manager', scope='window',
                                   window=win_id)

qutebrowser/commands/runners.py

@@ -74,9 +74,6 @@ class SearchRunner(QObject):
         Args:
             text: The text to search for.
             rev: Search direction, True if reverse, else False.
-
-        Emit:
-            do_search: If a search should be started.
         """
         if self._text is not None and self._text != text:
             # We first clear the marked text, then the highlights
@@ -124,9 +121,6 @@ class SearchRunner(QObject):
 
         Args:
             count: How many elements to ignore.
-
-        Emit:
-            do_search: If a search should be started.
         """
         if self._text is not None:
             for _ in range(count):
@@ -138,9 +132,6 @@ class SearchRunner(QObject):
 
         Args:
             count: How many elements to ignore.
-
-        Emit:
-            do_search: If a search should be started.
         """
         if self._text is None:
             return
@@ -209,9 +200,6 @@ class CommandRunner(QObject):
                       unknown.
             alias_no_args: Whether to apply an alias if there are no arguments.
 
-        Raise:
-            NoSuchCommandError if a command wasn't found.
-
         Return:
             A split string commandline, e.g ['open', 'www.google.com']
         """

qutebrowser/commands/userscripts.py

@@ -268,11 +268,7 @@ class _WindowsUserscriptRunner(_BaseUserscriptRunner):
         self._oshandle = None
 
     def on_proc_finished(self):
-        """Read back the commands when the process finished.
+        """Read back the commands when the process finished."""
-
-        Emit:
-            got_cmd: Emitted for every command in the file.
-        """
         log.procs.debug("proc finished")
         with open(self._filepath, 'r', encoding='utf-8') as f:
             for line in f:

qutebrowser/config/config.py

@@ -476,14 +476,6 @@ class ConfigManager(QObject):
             sectname: The name of the section to change.
             optname: The name of the option to change.
             value: The new value.
-
-        Raise:
-            NoSectionError: If the specified section doesn't exist.
-            NoOptionError: If the specified option doesn't exist.
-
-        Emit:
-            changed: If the config was changed.
-            style_changed: When style caches need to be invalidated.
         """
         try:
             value = self._interpolation.before_set(self, sectname, optname,

qutebrowser/config/configtypes.py

@@ -127,10 +127,6 @@ class BaseType:
 
         Args:
             value: The value to validate.
-
-        Raise:
-            ValidationError if the value was invalid.
-            NotImplementedError if self.valid_values is not defined and this
                                 method should be overridden.
         """
         if not value and self._none_ok:

qutebrowser/keyinput/basekeyparser.py

@@ -278,9 +278,6 @@ class BaseKeyParser(QObject):
 
         Args:
             command/count: As if passed to self.execute()
-
-        Emit:
-            keystring_updated to do a delayed update.
         """
         self._debug_log("Executing delayed command now!")
         self._timer = None
@@ -293,9 +290,6 @@ class BaseKeyParser(QObject):
 
         Args:
             e: the KeyPressEvent from Qt
-
-        Emit:
-            keystring_updated: If a new keystring should be set.
         """
         handled = self._handle_special_key(e)
         if handled or not self._supports_chains:

qutebrowser/keyinput/modeman.py

@@ -269,9 +269,6 @@ class ModeManager(QObject):
             mode: The mode to enter as a KeyMode member.
             reason: Why the mode was entered.
             override: Override a locked mode.
-
-        Emit:
-            entered: With the new mode name.
         """
         if not isinstance(mode, usertypes.KeyMode):
             raise TypeError("Mode {} is no KeyMode member!".format(mode))
@@ -314,9 +311,6 @@ class ModeManager(QObject):
         Args:
             mode: The name of the mode to leave.
             reason: Why the mode was left.
-
-        Emit:
-            left: With the old mode name.
         """
         try:
             self._mode_stack.remove(mode)

qutebrowser/keyinput/modeparsers.py

@@ -105,9 +105,6 @@ class HintKeyParser(keyparser.CommandKeyParser):
 
         Return:
             True if event has been handled, False otherwise.
-
-        Emit:
-            keystring_updated: Emitted when keystring has been changed.
         """
         log.keyboard.debug("Got special key 0x{:x} text {}".format(
             e.key(), e.text()))
@@ -143,9 +140,6 @@ class HintKeyParser(keyparser.CommandKeyParser):
 
         Args:
             e: the KeyPressEvent from Qt
-
-        Emit:
-            keystring_updated: If a new keystring should be set.
         """
         handled = self._handle_single_key(e)
         if handled and self._keystring:

qutebrowser/models/basecompletion.py

@@ -144,8 +144,5 @@ class BaseCompletionModel(QStandardItemModel):
         """Sort the data in column according to order.
 
         Override QAbstractItemModel::sort.
-
-        Raise:
-            NotImplementedError, should be overwritten in a superclass.
         """
         raise NotImplementedError

qutebrowser/models/cmdhistory.py

@@ -94,10 +94,6 @@ class History:
         """Get the previous item in the temp history.
 
         start() needs to be called before calling this.
-
-        Raise:
-            ValueError if start() wasn't called.
-            HistoryEndReachedError if the first item was reached.
         """
         if not self.is_browsing():
             raise ValueError("Currently not browsing history")
@@ -110,10 +106,6 @@ class History:
         """Get the next item in the temp history.
 
         start() needs to be called before calling this.
-
-        Raise:
-            ValueError if start() wasn't called.
-            HistoryEndReachedError if the last item was reached.
         """
         if not self.is_browsing():
             raise ValueError("Currently not browsing history")

qutebrowser/network/schemehandler.py

@@ -48,10 +48,6 @@ class SchemeHandler(QObject):
 
         Return:
             A QNetworkReply.
-
-        Raise:
-            NotImplementedError because this needs to be overwritten by
-            subclasses.
         """
         raise NotImplementedError
 
@@ -68,9 +64,6 @@ class SpecialNetworkReply(QNetworkReply):
             fileData: reference to the data buffer (QByteArray)
             mimeType: for the reply (string)
             parent: reference to the parent object (QObject)
-
-        Emit:
-            metaDataChanged and readyRead and finished after initializing.
         """
         super().__init__(parent)
 

qutebrowser/test/stubs.py

@@ -50,9 +50,6 @@ class ConfigStub:
         Args:
             name: The section name to get.
 
-        Raise:
-            ValueError if section isn't test1/test2.
-
         Return:
             The section as dict.
         """

qutebrowser/utils/completer.py

@@ -161,9 +161,6 @@ class Completer(QObject):
         Args:
             selected: New selection.
             _delected: Previous selection.
-
-        Emit:
-            change_completed_part: Emitted when there's data for the new item.
         """
         indexes = selected.indexes()
         if not indexes:

qutebrowser/utils/docutils.py

@@ -128,8 +128,6 @@ class DocstringParser:
         """Parse the long description in the docstring."""
         if line.startswith('Args:'):
             self._state = self.State.arg_start
-        elif line.startswith('Emit:') or line.startswith('Raise:'):
-            self._state = self.State.misc
         elif line.strip() == '//':
             self._state = self.State.desc_hidden
         elif line.strip():

qutebrowser/utils/editor.py

@@ -65,9 +65,6 @@ class ExternalEditor(QObject):
         """Write the editor text into the form field and clean up tempfile.
 
         Callback for QProcess when the editor was closed.
-
-        Emit:
-            editing_finished: If process exited normally.
         """
         log.procs.debug("Editor closed")
         if exitstatus != QProcess.NormalExit:
@@ -113,9 +110,6 @@ class ExternalEditor(QObject):
 
         Args:
             text: The initial text to edit.
-
-        Emit:
-            editing_finished with the new text if editing finshed successfully.
         """
         if self._text is not None:
             raise ValueError("Already editing a file!")

qutebrowser/utils/qtutils.py

@@ -68,9 +68,6 @@ def check_overflow(arg, ctype, fatal=True):
     Return
         The truncated argument if fatal=False
         The original argument if it's in bounds.
-
-    Raise:
-        OverflowError if the argument is out of bounds and fatal=True.
     """
     maxval = MAXVALS[ctype]
     minval = MINVALS[ctype]
@@ -119,11 +116,7 @@ def check_print_compat():
 
 
 def ensure_valid(obj):
-    """Ensure a Qt object with an .isValid() method is valid.
+    """Ensure a Qt object with an .isValid() method is valid."""
-
-    Raise:
-        QtValueError if the object is invalid.
-    """
     if not obj.isValid():
         raise QtValueError(obj)
 

qutebrowser/utils/urlutils.py

@@ -43,9 +43,6 @@ def _get_search_url(txt):
 
     Return:
         The search URL as a QUrl.
-
-    Raise:
-        FuzzyUrlError if there is no template or no search term was found.
     """
     log.url.debug("Finding search engine for '{}'".format(txt))
     r = re.compile(r'(^|\s+)!(\w+)($|\s+)')
@@ -186,9 +183,6 @@ def is_url(urlstr):
 
     Return:
         True if it is a valid URL, False otherwise.
-
-    Raise:
-        ValueError if the autosearch config value is invalid.
     """
     autosearch = config.get('general', 'auto-search')
 

qutebrowser/utils/usertypes.py

@@ -128,10 +128,6 @@ class NeighborList(collections.abc.Sequence):
 
         Return:
             The new item.
-
-        Raise:
-            IndexError if the border of the list is reached and mode is
-                       exception.
         """
         try:
             if self._idx + offset >= 0:
@@ -164,10 +160,6 @@ class NeighborList(collections.abc.Sequence):
 
         Return:
             The new item.
-
-        Raise:
-            IndexError if the border of the list is reached and mode is
-                       exception.
         """
         log.misc.debug("{} items, idx {}, offset {}".format(
             len(self._items), self._idx, offset))
@@ -324,11 +316,7 @@ class Question(QObject):
         self.completed.emit()
 
     def abort(self):
-        """Abort the question.
+        """Abort the question."""
-
-        Emit:
-            aborted: Always emitted.
-        """
         self.is_aborted = True
         try:
             self.aborted.emit()

qutebrowser/utils/utilcmds.py

@@ -61,10 +61,6 @@ def debug_crash(typ: ('exception', 'segfault')='exception'):
 
     Args:
         typ: either 'exception' or 'segfault'.
-
-    Raises:
-        raises Exception when typ is not segfault.
-        segfaults when typ is (you don't say...)
     """
     if typ == 'segfault':
         # From python's Lib/test/crashers/bogus_code_obj.py

qutebrowser/utils/utils.py

@@ -289,9 +289,6 @@ def _get_color_percentage(a_c1, a_c2, a_c3, b_c1, b_c2, b_c3, percent):
 
     Return:
         A (c1, c2, c3) tuple with the interpolated color components.
-
-    Raise:
-        ValueError if the percentage was invalid.
     """
     if not 0 <= percent <= 100:
         raise ValueError("percent needs to be between 0 and 100!")
@@ -313,9 +310,6 @@ def interpolate_color(start, end, percent, colorspace=QColor.Rgb):
 
     Return:
         The interpolated QColor, with the same spec as the given start color.
-
-    Raise:
-        ValueError if invalid parameters are passed.
     """
     qtutils.ensure_valid(start)
     qtutils.ensure_valid(end)

qutebrowser/widgets/statusbar/bar.py

@@ -411,9 +411,6 @@ class StatusBar(QWidget):
 
         Args:
             e: The QResizeEvent.
-
-        Emit:
-            resized: Always emitted.
         """
         super().resizeEvent(e)
         self.resized.emit(self.geometry())
@@ -423,9 +420,6 @@ class StatusBar(QWidget):
 
         Args:
             e: The QMoveEvent.
-
-        Emit:
-            moved: Always emitted.
         """
         super().moveEvent(e)
         self.moved.emit(e.pos())

qutebrowser/widgets/statusbar/command.py

@@ -145,9 +145,6 @@ class Command(misc.MinimalLineEditMixin, misc.CommandLineEdit):
 
         Args:
             text: The text to set as string.
-
-        Emit:
-            update_completion: Emitted if the text changed.
         """
         old_text = self.text()
         self.setText(text)
@@ -248,13 +245,7 @@ class Command(misc.MinimalLineEditMixin, misc.CommandLineEdit):
     @cmdutils.register(instance='status-command', hide=True,
                        modes=[usertypes.KeyMode.command], scope='window')
     def command_accept(self):
-        """Execute the command currently in the commandline.
+        """Execute the command currently in the commandline."""
-
-        Emit:
-            got_cmd: If a new cmd was entered.
-            got_search: If a new search was entered.
-            got_search_rev: If a new reverse search was entered.
-        """
         signals = {
             ':': self.got_cmd,
             '/': self.got_search,
@@ -285,10 +276,6 @@ class Command(misc.MinimalLineEditMixin, misc.CommandLineEdit):
 
         Args:
             mode: The mode which was left.
-
-        Emit:
-            clear_completion_selection: Always emitted.
-            hide_completion: Always emitted so the completion is hidden.
         """
         if mode == usertypes.KeyMode.command:
             self.setText('')

qutebrowser/widgets/statusbar/prompter.py

@@ -132,9 +132,6 @@ class Prompter(QObject):
 
         Return:
             The mode which should be entered.
-
-        Raise:
-            ValueError if the set PromptMode is invalid.
         """
         prompt = objreg.get('prompt', scope='window', window=self._win_id)
         if self._question.mode == usertypes.PromptMode.yesno:

qutebrowser/widgets/tabbedbrowser.py

@@ -188,9 +188,6 @@ class TabbedBrowser(tabwidget.TabWidget):
 
         Return:
             The current URL as QUrl.
-
-        Raise:
-            CommandError if the current URL is invalid.
         """
         widget = self.currentWidget()
         if widget is None:
@@ -208,11 +205,7 @@ class TabbedBrowser(tabwidget.TabWidget):
         return url
 
     def shutdown(self):
-        """Try to shut down all tabs cleanly.
+        """Try to shut down all tabs cleanly."""
-
-        Emit:
-            shutdown_complete if the shutdown completed successfully.
-        """
         try:
             self.currentChanged.disconnect()
         except TypeError:
@@ -240,9 +233,6 @@ class TabbedBrowser(tabwidget.TabWidget):
 
         Args:
             tab: The QWebView to be closed.
-
-        Raise:
-            ValueError if the tab is not in the QTabWidget.
         """
         idx = self.indexOf(tab)
         if idx == -1:
@@ -553,9 +543,6 @@ class TabbedBrowser(tabwidget.TabWidget):
 
         Args:
             e: The QResizeEvent
-
-        Emit:
-            resize: Always emitted.
         """
         super().resizeEvent(e)
         self.resized.emit(self.geometry())

qutebrowser/widgets/webview.py

@@ -128,11 +128,7 @@ class WebView(QWebView):
         return utils.get_repr(self, tab_id=self.tab_id, url=url)
 
     def _set_load_status(self, val):
-        """Setter for load_status.
+        """Setter for load_status."""
-
-        Emit:
-            load_status_changed
-        """
         if not isinstance(val, LoadStatus):
             raise TypeError("Type {} is no LoadStatus member!".format(val))
         log.webview.debug("load status for {}: {}".format(repr(self), val))
@@ -279,9 +275,6 @@ class WebView(QWebView):
 
         Return:
             Return status of self.load
-
-        Emit:
-            titleChanged
         """
         qtutils.ensure_valid(url)
         urlstr = url.toDisplayString()
@@ -412,9 +405,6 @@ class WebView(QWebView):
         Args:
             e: The QPaintEvent.
 
-        Emit:
-            scroll_pos_changed; If the scroll position changed.
-
         Return:
             The superclass event return value.
         """