'complete form' key missing from $form_state documentation

Here's a patch. When approved, this should go into both D7 and D8. Rolled against D8, but there shouldn't be any difference for D7.

Actually, I had a 3-4 part plan for reworking the $form_state keys lists, and you've gotten ahead of me, jhodgdon. :)

#1: Adding the 'complete form' key was the first part. It needs to be documented, there aren't really any questions about it except that my description is accurate and complete. It should be an easy issue to resolve.

#1a: The second was that the order of the keys seems random. Such a long list really needs to be alphabetized. But there's nothing controversial about that, so I'll reroll the patch to include alphabetizing.

#2: I think the duplication of the list should be its own issue. The 'Form generation' page looks like it should be a complete list of keys, and it doesn't include all the keys in the second list, as jhodgdon mentioned. There are also some differences in the descriptions, and the question of which list to keep and which gets a link. So there are decisions to be made about how to handle this that have nothing to do with whether 'complete form' gets included in the list.

#3: There are other keys that are not in either list. That should also be a separate issue to follow the resolution of #2.

I'd much prefer to get this simple addition in before tackling the more complicated questions.

I'll get that new patch in here sometime today. Meanwhile, is the description of 'complete form' complete and accurate?

EDITED: On second thought, alphabetizing the list should probably wait until after the decision about which list to keep. Then I'll alphabetize that list.

The reason I prefer to break this into chunks is to make faster progress on getting the documentation into core. 'complete form' came up in one of the changes to the FAPI reference. I researched it on d.o., it's fairly simple but also important. If a form specialist glances at the patch, it could be in core in a couple of days. It's almost as simple as correcting a wrong URL. Then it will be available to anyone who might need it.

The second chunk is more complicated. It's the kind of patch that can have a lot of differing opinions and sometimes get hung up on small issues. It could take quite awhile to get to the RTBC phase. That's time the 'complete form' key will be missing from the documentation if it's included in the larger issue.

The third chunk is even more challenging, since some of the keys have no documentation. That means writing descriptions of what they do from scratch, possibly tracking down experts for explanations. Seems to me it would be easier to do this after the question of the two lists is resolved.

But I really have no objection to combining the second and third. It won't keep any documentation off d.o. while it's being worked out, even if it does take longer to get a final version ready.

Yes, that's the idea. Just need someone to review what's in the patch.

EDITED: I think I misunderstood what you meant by both sets of documentation. Do you mean both lists? The patch only adds it to one. I was thinking you meant both versions of core, 7 and 8.

So I'll reroll the patch to include it in both places, once someone confirms the information is correct. And who knows, it may go in with your other issue before it gets approved here. :)

I've come to agree with you, jhodgdon. It really doesn't make sense to have a separate issue for this one key. I'm closing this as duplicate: main issue is #1170030: $form_state doc in two places and incomplete.

@jhodgdon
Here's an update on what happened with this issue. Couldn't find you on IRC, so I've left you a message there, with the explanation here.

Thanks for bearing with me as I learn the right way to deal with the issue queues. Sometimes I need to sleep on things to see more clearly.

After I closed this issue, I went looking for a completely separate issue I found while researching the 'complete form' key (about underscores in $form_state key names). I knew it was created by sun, in the 'forms system' component and included $form_state. So I searched on that and just by accident came across rfay's issue for the $form_state keys. I didn't find it before I created this issue because I searched only in the 'documentation' component, and rfay's issue was in the 'forms system' component. I've since moved it to 'documentation'.

Anyway, hope that clears things up. I felt it came to an abrupt end when I closed the issue you opened, and wanted to let you know what happened.