From bc68848600e2e7e1a474afb6f99ac882ec7de2d2 Mon Sep 17 00:00:00 2001
From: Roland Haroutiounian <roland.har@gmail.com>
Date: Fri, 24 Mar 2017 16:07:21 +0100
Subject: [PATCH] Documentation of the lodel.plugin.extensions and
 lodel.plugin.hooks modules

---
 lodel/plugin/extensions.py | 12 ++++++++++--
 lodel/plugin/hooks.py      | 35 ++++++++++++++++++-----------------
 2 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/lodel/plugin/extensions.py b/lodel/plugin/extensions.py
index 4c9c098..89653d8 100644
--- a/lodel/plugin/extensions.py
+++ b/lodel/plugin/extensions.py
@@ -1,3 +1,6 @@
+## @package lodel.plugin.extensions A package to manage the Extension plugins
+
+
 from lodel.context import LodelContext
 LodelContext.expose_modules(globals(), {
     'lodel.plugin.plugins': ['Plugin'],
@@ -7,9 +10,12 @@ LodelContext.expose_modules(globals(), {
 
 _glob_typename = 'extension'
 
-
+## @brief A class representing a basic Extension plugin
+# 
+# This class will be extended for each plugin of this type.
 class Extension(Plugin):
     
+    ## @brief Specifies the settings linked to this plugin
     _plist_confspecs = {
         'section': 'lodel2',
         'key': 'extensions',
@@ -20,6 +26,8 @@ class Extension(Plugin):
                 'ptype': _glob_typename,
                 'none_is_valid': False})
         }
-
+    
+    ## @brief A property defining the type's name of this plugin.
+    # By default, it's the global type name ("extension" here).
     _type_conf_name = _glob_typename
 
diff --git a/lodel/plugin/hooks.py b/lodel/plugin/hooks.py
index 3d58eba..db8df75 100644
--- a/lodel/plugin/hooks.py
+++ b/lodel/plugin/hooks.py
@@ -1,20 +1,22 @@
 #-*- coding: utf-8 -*-
 
+## @package lodel.plugin.hooks This module deals with the Hook management in Lodel
+
 import os
 import copy
 from lodel.context import LodelContext
 
 
-##@brief Class designed to handle a hook's callback with a priority
+## @brief Class designed to handle a hook's callback with a priority
 class DecoratedWrapper(object):
-    ##@brief Constructor
+    ##
     # @param hook function : the function to wrap
     # @param priority int : the callbacl priority
     def __init__(self, hook, priority):
         self._priority = priority
         self._hook = hook
     
-    ##@brief Call the callback
+    ## @brief Calls the callback
     # @param hook_name str : The name of the called hook
     # @param caller * : The caller (depends on the hook)
     # @param payload * : Datas that depends on the hook
@@ -22,12 +24,14 @@ class DecoratedWrapper(object):
     def __call__(self, hook_name, caller, payload):
         return self._hook(hook_name, caller, payload)
 
+    ## @brief Returns the string representation of the class
+    # It shows the name and the priority of the hook
     def __str__(self):
         return "<LodelHook '%s' priority = %s>" % (
             self._hook.__name__, self._priority)
 
-##@brief Decorator designed to register hook's callbacks
-#@ingroup lodel2_plugins
+## @brief Decorator designed to register hook's callbacks
+# @ingroup lodel2_plugins
 #
 # @note Decorated functions are expected to take 3 arguments :
 #  - hook_name : the called hook name
@@ -35,17 +39,17 @@ class DecoratedWrapper(object):
 #  - payload : datas depending on the hook
 class LodelHook(object):
     
-    ##@brief Stores all hooks (DecoratedWrapper instances)
+    ## @brief Stores all hooks (DecoratedWrapper instances)
     _hooks = dict()
     
-    ##@brief Decorator constructor
+    ##
     # @param hook_name str : the name of the hook to register to
-    # @param priority int : the hook priority
+    # @param priority int : the hook priority (default value : None)
     def __init__(self, hook_name, priority = None):
         self._hook_name = hook_name
         self._priority = 0xFFFF if priority is None else priority
     
-    ##@brief called just after __init__
+    ## @brief called just after __init__
     # @param hook function : the decorated function
     # @return the hook argument
     def __call__(self, hook):
@@ -56,11 +60,10 @@ class LodelHook(object):
         self._hooks[self._hook_name] = sorted(self._hooks[self._hook_name], key = lambda h: h._priority)
         return hook
 
-    ##@brief Call hooks
+    ## @brief Calls a hook
     # @param hook_name str : the hook's name
     # @param caller * : the hook caller (depends on the hook)
     # @param payload * : datas for the hook
-    # @param cls
     # @return modified payload
     @classmethod
     def call_hook(cls, hook_name, caller, payload):
@@ -73,10 +76,9 @@ class LodelHook(object):
                 payload = hook(hook_name, caller, payload)
         return payload
     
-    ##@brief Fetch registered hooks
-    # @param names list | None : optionnal filter on name
-    # @param cls
-    # @return a list of functions
+    ## @brief Fetches registered hooks
+    # @param names list | None : optionnal filter on name (default value : None)
+    # @return dict containing for each name a list of the hooks and their priorities
     @classmethod
     def hook_list(cls, names = None):
         res = None
@@ -86,8 +88,7 @@ class LodelHook(object):
             res = copy.copy(cls._hooks)
         return { name: [(hook._hook, hook._priority) for hook in hooks] for name, hooks in res.items() }
     
-    ##@brief Unregister all hooks
-    # @param cls
+    ## @brief Unregister all hooks
     # @warning REALLY NOT a good idea !
     # @note implemented for testing purpose
     @classmethod