some more documentation

mathcaptcha.php

@@ -13,6 +13,17 @@ use Friendica\Core\L10n;
 use Friendica\Core\Renderer;
 use Friendica\Core\System;
 
+/*
+ * We will provide alternate templates for the register.tpl template.
+ * This is done with the register_form hook. The user input has then
+ * be evaluated with the register_post hook. To get the content into
+ * the new fields of the registration.tpl we need to supply the variables
+ * with the template_vars hook.
+ *
+ * So 1st registration of these hooks during the installation of the
+ * addon and then unregistration of the hooks when the addon is
+ * uninstalled.
+ */
 function mathcaptcha_install()
 {
     Hook::register('register_form', 'addon/mathcaptcha/mathcaptcha.php', 'mathcaptcha_register_form');
@@ -29,6 +40,11 @@ function mathcaptcha_uninstall()
 
 /**
  * Check if the captcha was solved correctly when posting the registration form
+ *
+ * If it is, let the default registration process proceed. If not, redirect the
+ * user back to the registration form and show a notice why the process failed.
+ *
+ * @param b		array holding the posted field from the registration form
  */
 function mathcaptcha_register_post(App $a, &$b)
 {
@@ -57,7 +73,11 @@ function mathcaptcha_register_post(App $a, &$b)
 }
 
 /**
- * Add the captcha to the register form
+ * Load an alternative register.tpl file that contains additional fields
+ * for the captcha. Should there be a theme specific one, use that instead
+ * of the default remplate.
+ *
+ * @param b		the SMARTY template object for the registration form
  */
 function mathcaptcha_register_form(App $a, &$b)
 {
@@ -79,7 +99,11 @@ function mathcaptcha_register_form(App $a, &$b)
 }
 
 /**
- * add template variables to the registration template
+ * Add template variables to the registration template. Additionally
+ * store the captcha information in the session variable of the Friendica
+ * PHP session.
+ *
+ * @param $arr		Array holding the variables applied to the template
  */
 function mathcaptcha_template_vars(App $a, &$arr)
 {