Document all arguments to hook_captcha() and fix broken documentation

I slightly disagree about the steps that should be taken here, I'd suggest:

1. Move captcha_api.txt to docs/
2. Create a proper captcha.api.php
3. Rename captcha_api.txt to api.md

captcha_api.txt renamed as api.md

Last step "Create a proper captcha.api.php"

I have checked the core modules and we need to remove the docs folder. we need to add the file captcha.api.php inside the captcha module folder. Also, I don't think we need to add any .md files in this folder.
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. Strictly speaking, it is not necessary to send the CAPTCHA session id with the form, as the one time CAPTCHA token is enough. However, we still send it along, because it can help debugging problems on live sites with only access to the markup.

Updated Patch.

Bumping to normal as its only related to documentation.

Rerolled the patch

Assuming documentation will not block the release.

This issue need documentation changes.So it's more of a task rather than bug.

Documented all arguments & fix the broken documentations.

Updated patch, removed the Cl error.

same patch again for testing against boat.

It shouldn't be code component I guess. Documentation component is not listed so changing it to Miscellaneous.

So, if we are renaming captcha_api.txt to captcha.api.php, we need to make sure we have all syntax right.

21:36:31 PHP Parse error: syntax error, unexpected '.' in /var/www/html/modules/contrib/captcha/captcha.api.php on line 120

What's happening is DrupalCI is trying parse the file, and fails due to syntax errors as it considers it to a valid php file.

@Yogesh Pawar You might have to make the syntax right in file, specially convert this to string:

        $captcha['solution'] = ...
        $captcha['form'] = ...

Also you might have to club the examples of hooks implementation as there are multiple declarations. You can track syntax errors by using command:

php <filename>

I am a novice. Can someone help me to fix this?
Or is this assigned to someone else?

As someone is working on this issue! Can someone please redirect me to some novice unassigned issue?

@utkarsh_malviya Pick up documentation bugs on contributed modules as beginner :)

Thanks @navneet0693 for your comment #34.
please review this updated patch.

Yet another patch to remove Cl error.

1. +++ b/captcha.api.php
   @@ -99,89 +88,71 @@ function foo_captcha_menu($may_cache) {
   + *   on succes and FALSE on failure.
   ...
   + *   on succes and FALSE on failure.
   

   Let's not leave any stones unturned.

2. +++ b/captcha.api.php
   @@ -189,19 +160,20 @@ insufficient for complex forms.
   +- 'path': path (array of path items) of the form's container element in which
   ...
   +- 'key': the key of the element before which the CAPTCHA element
   ...
   +- 'weight': if 'key' is not NULL: should be the weight of the element defined
   

   Indentation needs to be clear.

Nice work! Rearranging the implementation examples were indeed needed.

Thanks @navneet0693. Changes done as per comment #41

Good to go now :)

@elachlan, Did you forget to update the status?

@hass,
Thanks for opening that. Please open a new issue for 7.x

As per BC policy https://www.drupal.org/core/backport-policy#d7

Where an issue filed against 8.x also applies to 7.x, a separate issue should be opened against 7.x, related to 8.x via the 'Parent issue' field (this can be done using the "Add child issue" link on the 8.x issue).

@hass - i have created a child issue which applies on the branch 7.x-1.x-dev as per comment #48. Issue link #2842669: [D7] Document all arguments to hook_captcha() and fix broken documentation.

@hass - i got your point, will change this & update the patch now.

Updated patch as per comment #53

bumping its priority to normal

Hass, I spent some time going through the code and as far as I can see this is what the $captcha_sid does.

The $captcha_sid is a unique identifier for an instance of the captcha. State information on each captcha session is stored in captcha_sessions, such as is solved status.

I'll leave it up to yogesh to do up another patch.

Thanks @elachlan & @hass for the help to improve captcha.api.php, updated the patch as per comment #58 & #57

There is a spelling mistake in there. It should say "such as its solved status."

We also need more information on how to use it. For instance because its unique to the session, image captcha uses it for a "static" url for the images for the captcha. The URL remains the same, but the image code changes.

I think @hass would agree that it is really up to the developer how they want to use the $captcha_sid, but at its base it really just uniquely identifies a session.

I'm not sure I understand how this issue is working, as several commits seem to have been made but it's still in 'needs work'.

At any rate, there is an error in several of the hooks in the api.php file:

function foo_captcha_captcha($op, $captcha_type = '') {

The function name must start with 'hook_', not 'foo_'.

This breaks analysis tools such as the API module and Module Builder.

Change made as per #64

Could someone please help with review here to get this fixed? I guess this also needs a reroll. Perhaps as MR then?

I agree with @joachim in #64, I will create a new issue to fix the remaining issues.

CLOSED, duplicate of #3322230: Fix problems inside "captcha.api.php"