From 1355a7e5d30720de325291c6f0b699f055c35852 Mon Sep 17 00:00:00 2001
From: tobi-wan-kenobi <tobi-wan-kenobi@users.noreply.github.com>
Date: Sat, 16 May 2020 15:28:15 +0200
Subject: [PATCH] [core/decorators] add docstrings

---
 bumblebee_status/core/decorators.py | 33 +++++++++++++++++++++++++++++
 docs/other/NOTES.md                 |  1 +
 2 files changed, 34 insertions(+)

diff --git a/bumblebee_status/core/decorators.py b/bumblebee_status/core/decorators.py
index b117f7b..8c60c70 100644
--- a/bumblebee_status/core/decorators.py
+++ b/bumblebee_status/core/decorators.py
@@ -6,6 +6,15 @@ import util.format
 log = logging.getLogger(__name__)
 
 
+"""Specifies that a module should never update (i.e. has static content).
+This means that its update() method will never be invoked
+
+:param init: The __init__() method of the module
+
+:return: Wrapped method that sets the module's interval to "never"
+"""
+
+
 def never(init):
     def call_init(obj, *args, **kwargs):
         init(obj, *args, **kwargs)
@@ -15,6 +24,16 @@ def never(init):
     return call_init
 
 
+"""Specifies the interval for executing the module's update() method
+
+:param hours: Hours between two update() invocations, defaults to 0
+:param minutes: Minutes between two update() invocations, defaults to 0
+:param seconds: Seconds between two update() invocations, defaults to 0
+
+:return: Wrapped method that sets the module's interval correspondingly
+"""
+
+
 def every(hours=0, minutes=0, seconds=0):
     def decorator_init(init):
         def call_init(obj, *args, **kwargs):
@@ -27,6 +46,20 @@ def every(hours=0, minutes=0, seconds=0):
     return decorator_init
 
 
+"""Specifies that the module's content should scroll, if required
+
+The exact behaviour of this method is governed by a number of parameters,
+specifically: The module's parameter "scrolling.width"  specifies the width when
+scrolling starts, "scrolling.makewide" defines whether the module should be expanded
+to "scrolling.width" automatically, if the content is shorter, the parameter
+"scrolling.bounce" defines whether it scrolls like a marquee (False) or should bounce
+when the end of the content is reached. "scrolling.speed" defines the number of characters
+to scroll each iteration.
+
+:param func: Function for which the result should be scrolled
+"""
+
+
 def scrollable(func):
     def wrapper(module, widget):
         text = func(module, widget)
diff --git a/docs/other/NOTES.md b/docs/other/NOTES.md
index 3ba0c14..4ff62c4 100644
--- a/docs/other/NOTES.md
+++ b/docs/other/NOTES.md
@@ -9,6 +9,7 @@
 - use __ for private
 
 ## Improvements
+- app launcher (list of apps, themeable)
 
 ## TODO
 - themes: use colors to improve theme readability