[D7] Document all arguments to hook_captcha() and fix broken documentation

+++ b/captcha.api.php
@@ -0,0 +1,180 @@
+ * This documentation is for developers that want to implement their own
+ * challenge type and integrate it with the base CAPTCHA module.
+ * === Required: hook_captcha($op, $captcha_type='', $captcha_sid = NULL) ===
+ * The hook_captcha() hook is the only required function if you want to
+ * integrate with the base CAPTCHA module.
+ * 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.
+ * 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()) and it is used for every session.
+ * Let's give a simple example to make this more clear.
+ * We create the challenge 'Foo CAPTCHA', which requires the user to
+ * enter "foo" in a textfield.

We use @param to explain parameters.

+++ b/captcha.api.php
@@ -0,0 +1,180 @@
+function foo_captcha_captcha($op, $captcha_type = '', $captcha_sid = NULL) {

$captcha_sid is not documented.

For about 15 years we are not duplicating cases. Where has this rule changed? We use need backport tag and move the casebetween branches once committed. This was we prevent regressions.

What is captcha session ID for and how does it work and what do I need to do as developer when I use it and how should I use it or for what. Nothing answered here. This is not helpful.