diff --git a/captcha.api.php b/captcha.api.php
index 8358d45..46326d9 100644
--- a/captcha.api.php
+++ b/captcha.api.php
@@ -13,10 +13,11 @@
 /**
  * The hook is the only required function if you want to integrate with the base CAPTCHA module
  *
- * Modules may make changes to the comment before it is saved to the database.
- * Functionality depends on the first argument $op:
- * 'list': you should return an array of possible challenge types that your module implements.
- * 'generate': generate a challenge.
+ * @param $op
+ *   The captcha operation to be performed, such as 'list', 'generate', or 'delete'.
+ * @param $captcha_type
+ *   Type of captcha to be generated, such as Math, Test, ...
+ * @return
  *  You should return an array that offers form elements and the solution
  *    of your challenge, defined by the second argument $captcha_type.
  *    The returned array $captcha should have the following items:
@@ -28,11 +29,7 @@
  *    available for more advanced challenges (e.g. the image CAPTCHA uses this
  *    argument, see image_captcha_captcha()).
  **/
-
-/**
- * Implementation of hook_captcha().
- */
-function hook_captcha_captcha($op, $captcha_type='') {
+function hookgi_captcha_captcha($op, $captcha_type='') {
   switch ($op) {
     case 'list':
       return array('Foo CAPTCHA');
@@ -57,11 +54,23 @@ function hook_captcha_captcha($op, $captcha_type='') {
  * validation of the responses. If this is not sufficient, you can provide
  * your own validation function with the 'captcha_validate' field, illustrated
  * by the following example:
+ *
+ * @param $op
+ *   The captcha operation to be performed, such as 'list', 'generate', or 'delete'.
+ * @param $captcha_type
+ *   Type of captcha to be generated, such as Math, Test, ...
+ * @return
+ *  You should return an array that offers form elements and the solution
+ *    of your challenge, defined by the second argument $captcha_type.
+ *    The returned array $captcha should have the following items:
+ *    $captcha['solution']: this is the solution of your challenge
+ *    $captcha['form']: an array of the form elements you want to add to the form.
+ *      There should be a key 'captcha_response' in this array, which points to
+  *      the form element where the user enters his answer.
+ *    An optional additional argument $captcha_sid with the captcha session ID is
+ *    available for more advanced challenges (e.g. the image CAPTCHA uses this
+ *    argument, see image_captcha_captcha()).
  **/
-
-/**
- * Implementation of hook_captcha().
- */
 function foo_captcha_captcha($op, $captcha_type='') {
   switch ($op) {
     ...
@@ -96,26 +105,25 @@ function foo_captcha_custom_validation($solution, $response) {
  * at the bottom of the targeted form, but this automatic detection may be insufficient
  * for complex forms.
  * The hook_captcha_placement_map hook allows to define the placement of the CAPTCHA element
- * as desired. The hook should return an array, mapping form IDs to placement arrays, which are
- * associative arrays with the following fields:
- *   - 'path': path (array of path items) of the form's container element in which the
- *     CAPTCHA element should be inserted.
- *   - 'key': the key of the element before which the CAPTCHA element
- *     should be inserted. If the field 'key' is undefined or NULL, the CAPTCHA will
- *     just be appended in the container.
- *   - 'weight': if 'key' is not NULL: should be the weight of the element defined by 'key'.
- *     If 'key' is NULL and weight is not NULL/unset: set the weight property of the CAPTCHA element
- *     to this value.
- * 
+ * as desired. 
+ *
+ * @return
+ *   The hook should return an array, mapping form IDs to placement arrays, which are
+ *   associative arrays with the following fields:
+ *     - 'path': path (array of path items) of the form's container element in which the
+ *       CAPTCHA element should be inserted.
+ *     - 'key': the key of the element before which the CAPTCHA element
+ *       should be inserted. If the field 'key' is undefined or NULL, the CAPTCHA will
+ *       just be appended in the container.
+ *     - 'weight': if 'key' is not NULL: should be the weight of the element defined by 'key'.
+ *       If 'key' is NULL and weight is not NULL/unset: set the weight property of the CAPTCHA element
+ *       to this value.
+ *
  * This will place the CAPTCHA element
  * - in the 'my_fancy_form' form inside the container $form['items']['buttons'],
  *   just before the element $form['items']['buttons']['sacebutton'].
  * - in the 'another_form' form at the toplevel of the form, with a weight 34.
  **/
-
-/**
- * Implementation of hook_captcha_placement_map
- */
 function hook_captcha_placement_map() {
   return array(
     'my_fancy_form' => array(