Expand documentation for system_settings_form()

We could use to expand this documentation now in D7, the backport.

Marking #1189516: system_settings_form does not really explain what it does as a duplicate of this. It has further documentation.

Here is my comment from that issue:

system_settings_form() is a really nifty helper for module admin settings forms that allow the user to edit variables (ie the things you variable_get().

You call it with your $form array at the end of your form builder. It does this:

- adds standard buttons for saving & resetting
- adds a submit handler which saves $form['foo'] as variable 'foo', ie does variable_set('foo', form values)
- (D7 and up IIRC) populates the $form's default values with the results of variable_get().

When you should use it:
- your settings form saves variables
- your settings form saves variables + other things

If you need to save other things, or you need to massage the form values before they are saved to variables, you can add in your own submit handler to run before the system one and:
- unset form values you don't want to be saved as variables (eg, ones you are saving yourself in a table)
- massage form values you want to be saved in a different format (eg, arrays of things).

system_settings_form() is being removed in D8 (see #1696224: Remove system_settings_form()) so I'm marking this wont fix.

Would be nice to have this in D7 though.

+1 on the idea of taking the patch above, making it conform to our documentation standards, and getting it into D7 and possibly D6. Since there was a patch but it needs work, changing status appropriately.

Standards needing attention:
- first line of function doc (verb, blank line following)
- all functions mentioned end in ()

Also I think the docs need rewriting a bit, since they're inconsistent as to what happens directly in this function and what happens in the submit (probably what the submit does should be documented on the submit, and referenced from system_settings_form()?).

chriscohen: thanks for your original patch! It would be great if you wanted to clean it up so we could get it committed. :) If not, I'm at least tagging it "novice" so that maybe someone will pick it up.

This is my first patch, I hope it's ok.

Thanks for the new patch, and welcome to Drupal Core contributing!

This still needs some work:

a) We have a standard way to document form submit functions:
https://drupal.org/node/1354#forms

b) All of the documentation needs some grammar fixes, rewriting for clarity, and proofreading.

c) For the system_settings_form() function, the first line should start with "Adds" not "Add".

d) In the first paragraph of the system_settings_form() added documentation, it says it "calls" the submit handler. That is not true. It just sets up the submit handler. It also says that the submit handler "creates" a submit handler, and that is not very good terminology.

e) Please do not use "eg". It is almost always misused and misunderstood, and almost always (as here), punctuated incorrectly. Please use "for example" instead.

Thanks for your help!! It's a pleasure for me to help the community. I really want to learn as much as possible. Please, if the patch is not correct yet, let me know. I'd like to do it well.

Much better, thanks! It still needs a bit of work... I think the general idea is good, but the wording is very conversational and sounds more like marketing rather than documentation. We just want to document what the function *does*, not try to induce someone to want to call the function.

So how about changing the first line to "Sets up a form to save information automatically." Then the next part could say something like:

This function adds a submit handler and a submit button to a form array. The submit function saves all the data in the form, using variable_set(), to variables named the same as the keys in the form array. Note that this means you should normally prefix your form array keys with your module name, so that they are unique when passed into variable_set().

If you need to manipulate the data in a custom manner, you can either put your own submission handler in the form array before calling this function, or just use your own submission handler instead of calling this function.

Then we can probably omit most of the documentation that is in the submission handler and the main function. Keep in mind that most people will not actually be clicking through to read the submit function documentation, so anything important for the user to know should be in the main system_settings_form() documentation, not in the submit handler docs. And I just don't think we need to go into as much detail as what is there -- this is reference documentation, not a tutorial.

Thoughts?

+ * This function makes easy for us to save form's data. It provides a
+ * 'Save configuration' button and sets up the submit handler. It will also
+ * shows a green confirmation message when data is successfully saved, and a
+ * red error message if something went wrong.
+ *
+ * It can be used to quickly create a form without the need to write a submit
+ * handler. You simply call to system_settings_form() with your $form array at
+ * the end of your form builder.

I really appreciate your patience. I cleaned up the submission handler documentation to adapt it what you said in #10 comment, a) section. If I acted wrong, tell me please. Thanks so much.

Looks good to me! I guess I wrote the text, so it should. :) I'll leave this for a few days in case anyone else has a comment about the text.

That was odd. For some reason, a notification about a very old patch was just generated.

Thanks again everyone! Committed to 7.x.

Is it really committed jhodgdon? I can't find it. It was a pleasure! :D

I believe so. http://drupalcode.org/project/drupal.git/commitdiff/ae919dbaa8c7faf15096...

There may be problems with tar/zip downloads on drupal.org right now... there have been some recently... but it is there in git.