[Meta] Improve documentation for Render and Form Elements

Thanks for creating this issue!

We've been discussing this in #documentation. Here's a summary of what ideas we have for improving the Form API documentation in its various forms.

1. The documentation that we want to improve exists in various places but this issue will aim to keep track and organize the whole effort. When "child" issues are created in this or other projects, or docs pages or guides added or updated, we'll add links to them here for the purposes of seeing and tracking our progress.
2. Similar to how the Migration system has wiki pages for plugins as well as @docblocks in the class code, the idea is to both improve the @docblocks and provide wiki pages with extended documentation and examples.
3. One idea is to update the Form API guide (Drupal APIs Wiki) with a sub-guide that focuses on Form and Render Elements. This Form and Render Elements sub-guide would contain pages for each of the elements and would follow the prescribed template (more on this template later).
4. For each form and render element here: https://api.drupal.org/api/drupal/elements, review and potentially update the @docblock to ensure that it is clear and complete. Any issues would be filed in the Drupal core project issue queue.
5. A documentation template has already been worked on and can be found in this Google Doc. Getting a consensus on this template should be one of the "todos" for this issue.

For others involved in the discussion, is this a good summary? Anything missing?

I propose that this issue focus on the following:

1. Decide on a scope. We could decide to only work on adding the sub-guide on Form and Render Elements to the existing Form API guide and leave the @docblocks as-is. Or we could do both. If we do both, we would also create a plan issue in the Drupal core issue queue that is scoped only to @docblock updates to Element classes here, and would include any existing issues that deal with that: https://api.drupal.org/api/drupal/elements.
2. Decide on the documentation template. Decide if it is a marked improvement, if anything should be changed about it, and decide the scope of what it applies to. Does it apply to just wiki pages in the proposed Elements sub-guide, or would it apply to @docblocks as well (and with what modifications?).
3. Find existing issues in this queue, the Drupal core issue queue (perhaps in the "documentation" component) and add links to them here. We may find other ideas for improving the docs in these issues.

How does #3, in the first section, relate to the existing page, Form Render Elements?

I'd like #4 to be done, not 'should' be done. The API documentation should be the source of truth and then the wiki pages can be more about use cases and examples. I don't know is in the core queue for improving the documentation for forms and elements but I'll take a look sometime this week.

@GersonJL, I assume you mean “Form API reference” issues from Drupal 7, correct, we only want to focus on Drupal 8+ Form API issues. You can apply a Drupal version filter in your issue search to only search for Drupal 8, 9, 10 issues. Feel free to ask further questions about using the searching the issue queue in the #documentation channel.

There will be a Slack-only meeting about this plan in the Drupal Slack #documentation channel this Thursday, Oct 13, 2022 at 18:00 UTC.

https://drupal.slack.com/archives/C220WV2TW/p1665521616666759

https://www.timeanddate.com/worldclock/meetingdetails.html?year=2022&mon...

This is a great idea. Thanks for working on it.

There's also an existing Render API guide, and personally I think it makes the most sense for the documentation about render elements, both form and markup, to be there. Maybe the template for the page could contain some kind of consistent visual indicator that lets you know the element you're currently looking at is a Form element and will only work in the $form.

We could create a new Render Element's section in the Render API guide. Example:

Render API
- Render Elements
-- What are Render Elements?
-- Actions
-- Ajax
-- Button (FormElement)
-- ...
-- View
-- Weight
-- Define a Custom Render Element

And then the Form API Render Element docs could be updated to point to those new pages, explain that form arrays are a superset of render arrays, and provide examples how render elements are used in a form. Or something like that.

As we've discussed in the Slack #documentation channel, I think we want to keep the scope of this to just Render Elements (which includes Form Elements). Updating the title accordingly.

This page used to be a useful partial list of element types

Form and render elements - 9.5.x - drupal
https://api.drupal.org/api/drupal/elements/9

But in version 10 it is reduced to one type, Component. Version 11 splurges on two types, Component and Ajax.

If there was some kind of link to some other place to find the information that would be one thing. This is subpar.

For me, the most important missing documentation is that we need a Drupal 10/11 version of the Drupal 7 "Form API Reference" page. Perhaps this is done as more than one page, but somewhere there needs to be list of valid values for #type and a way to find out what properties can be used with each type.

The link to the template in the issue summary is a 404.

Related issues are in the sidebar