Create Documentation For Button Form Elements

Thanks, looks pretty good! A few small suggestions:

1. +++ b/core/lib/Drupal/Core/Render/Element/Button.php
   @@ -16,6 +16,21 @@
   + *   an empty array to supress all form validation errors.
   

   supress => suppress
   (typo)

2. +++ b/core/lib/Drupal/Core/Render/Element/Button.php
   @@ -16,6 +16,21 @@
   + *   '#value => $this->t('Preview'),
   

   Do you think we should mention here that #value is the text shown on the button? This is different from the standard meaning of the #value property for other elements, and is necessary in order to create a button that will actually work in a form.

3. +++ b/core/lib/Drupal/Core/Render/Element/Dropbutton.php
   @@ -10,6 +10,25 @@
   + * - #links: An array of links to actions.
   

   I can see it in the usage example, but maybe we should explicitly document what the array elements are?

4. +++ b/core/lib/Drupal/Core/Render/Element/Dropbutton.php
   @@ -10,6 +10,25 @@
   + * @code
   

   Missing the usual "Usage Example" header here.

5. +++ b/core/lib/Drupal/Core/Render/Element/Submit.php
   @@ -13,6 +13,21 @@
   + *   the object and method name (e.g. [ $this, 'methodName'] ).
   

   punctuation:

   (e.g., ...

6. +++ b/core/lib/Drupal/Core/Render/Element/Submit.php
   @@ -13,6 +13,21 @@
   + *   '#value' => $this->t('Save'),
   

   Like in Button, I think we should document #value here.

Ah... hm... Yes, I think saying "See Link for additional info" (with your wording) makes the most sense. But. Is this using the link *theme* functions or the link *element* for rendering? Let's see... looks like it is using the theme function. So I think the proper thing to reference would be the links.html.twig template, which should have docs about the links... let's see if it does. Yes.

So really the dropbutton is just a wrapper for theme 'links__dropbutton' with a bit of wrapper prerendering, and I think rather than documenting #links specifically, we should point to links.html.twig, which has docs for several other properties as well as #links.

Hm. I'm looking at the prerender function in Dropbutton. It looks like it also supports a #subtype property, which if it is set, adds this to the #theme property. So if #theme was set to for instance the default of 'links__dropbutton', and #subtype is set to 'operations', it will make #theme into 'links__dropbutton__operations'.

Hope this makes sense.

I guess we should look through the other render elements and make sure there aren't any other properties being used by them that we should document, if you haven't been looking for these?

Ah. Yeah, we should really point them at the template_preprocess_links() function, which documents the un-preprocessed information ...

So how about if we say something like:

This element uses the 'links' theme hook for rendering [say something about that it's actually links__dropbutton by default plus whatever is in #subtype]. See template_preprocess_links() for documentation on the properties used in theming; for instance, use element property #links to provide $variables['links'] for theming.

Not sure of wording... something like that?

OK, this looks good. One nitpick:

+++ b/core/lib/Drupal/Core/Render/Element/Submit.php
@@ -13,6 +13,22 @@
+ *   the object and method name (e.g. [ $this, 'methodName'] ).

punctuation: After e.g., you need a comma. Or better yet (since e.g. and i.e. are confused/misused nearly always in Drupal API docs) just write out "for example,".

And I still think we should document #subtype. The element explicitly uses it, and it's specific to this type of element. I still like my suggestion in #7. Specific suggestion:

By default, this element sets #theme so that the 'links' theme hook is used for rendering, with suffixes so that themes can override this specifically without overriding all links theming. If the #subtype property is provided in your render array with value 'foo', #theme is set to links__dropbutton_foo; if not, it's links__dropbutton_foo; both of these can be overridden by setting the #theme property in your render array. See template_preprocess_links() for documentation on the other properties used in theming; for instance, use element property #links to provide $variables['links'] for theming.

And then in Operations maybe mention that #subtype is given a value by default?

Looking good!

A few questions/comments remain:

1. +++ b/core/lib/Drupal/Core/Render/Element/Button.php
   @@ -16,6 +16,23 @@
   + * - #limit_validation_errors: An array of form element keys that reference the
   + *   sections of the form validations that will block form submission. Specify
   

   Um... This is confusing to me. What are "sections of the form validations"? I don't understand what this is saying.

2. +++ b/core/lib/Drupal/Core/Render/Element/Dropbutton.php
   @@ -10,6 +10,37 @@
   + * your render array with value 'foo', #theme is set to links__dropbutton_foo;
   + * if not, it's links__dropbutton_foo; both of these can be overridden by
   

   Whoops, I had two typos in #11 that you copied into here. I think if there is no #subtype, it's links__dropbutton, and if foo is provided, I think it's links__dropbutton__foo (with a double-underscore). I hope so anyway.

Much better! One small typo and I think we're done here:

+++ b/core/lib/Drupal/Core/Render/Element/Button.php
@@ -16,6 +16,23 @@
+ * - #limit_validation_errors: An array of form element keys that will block
+ *   form submission when validation for these elements or any child elements
+ *   fail. Specify an empty array to suppress all form validation errors.

fail -> fails
in the last line (it is saying "... when validation ... fails.")

Thanks! I think metzlerd would have finished up this issue, but that's OK.

Tagging for "it's OK to commit now". Just API docs.

Committed 78aba37 and pushed to 8.0.x. Thanks!