From 4df7f1cc01638963c46ca9d0adfd129aa227ad73 Mon Sep 17 00:00:00 2001
From: Ferdinand Thiessen <rpm@fthiessen.de>
Date: Sun, 19 Dec 2021 18:58:57 +0100
Subject: [PATCH] docs(plugins): Some more documentation on the plugin class

---
 flaschengeist/plugins/__init__.py | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/flaschengeist/plugins/__init__.py b/flaschengeist/plugins/__init__.py
index 1b6f701..6932110 100644
--- a/flaschengeist/plugins/__init__.py
+++ b/flaschengeist/plugins/__init__.py
@@ -54,10 +54,21 @@ class Plugin:
     If your class uses custom models add a static property called ``models``"""
 
     blueprint = None  # You have to override
+    """Override with a `flask.blueprint` if the plugin uses custom routes"""
     permissions = []  # You have to override
+    """Override to add custom permissions used by the plugin
+    
+    A good style is to name the permissions with a prefix related to the plugin name,
+    to prevent clashes with other plugins. E. g. instead of *delete* use *plugin_delete*.
+    """
     id = "dev.flaschengeist.plugin"  # You have to override
+    """Override with the unique ID of the plugin (Hint: FQN)"""
     name = "plugin"  # You have to override
+    """Override with human readable name of the plugin"""
     models = None  # You have to override
+    """Override with models module"""
+    migrations_path = None  # Override this with the location of your db migrations directory
+    """Override with path to migration files, if custome db tables are used"""
 
     def __init__(self, config=None):
         """Constructor called by create_app
@@ -68,17 +79,21 @@ class Plugin:
 
     def install(self):
         """Installation routine
+
         Is always called with Flask application context
         """
         pass
 
     def get_setting(self, name: str, **kwargs):
         """Get plugin setting from database
+
         Args:
             name: string identifying the setting
             default: Default value
         Returns:
             Value stored in database (native python)
+        Raises:
+            `KeyError` if no such setting exists in the database
         """
         try:
             setting = (
@@ -95,6 +110,7 @@ class Plugin:
 
     def set_setting(self, name: str, value):
         """Save setting in database
+
         Args:
             name: String identifying the setting
             value: Value to be stored
@@ -114,10 +130,22 @@ class Plugin:
         db.session.commit()
 
     def notify(self, user, text: str, data=None):
+        """Create a new notification for an user
+        
+        Args:
+            user: `flaschengeist.models.user.User` to notify
+            text: Visibile notification text
+            data: Optional data passed to the notificaton
+        Returns:
+            ID of the created `flaschengeist.models.notification.Notification`
+
+        Hint: use the data for frontend actions.
+        """
         if not user.deleted:
             n = Notification(text=text, data=data, plugin=self.id, user_=user)
             db.session.add(n)
             db.session.commit()
+            return n.id
 
     def serialize(self):
         """Serialize a plugin into a dict