For years, brave Drupal community volunteers have been maintaining the Form API (FAPI) Reference, which is currently being displayed on api.drupal.org, and is part of the Documentation git repository. This lists all the form elements and all their properties, but it is VERY difficult to maintain (the file is hard to edit). It also suffers from being far from the Drupal Core code that it is documenting, so when elements and properties in Drupal Core are updated, the FAPI reference is usually not updated until someone notices it's out of date and files a separate issue.
1. Move the documentation of form/render array elements/properties into the core source code (documentation headers -- exact format to be determined -- see sections below).
2. Have the API module parse these documentation headers and generate a page substantially similar to the current FAPI reference (and probably a separate page as a render API reference, which doesn't currently exist at all). There's a separate issue about having the API module do this:
#100680: Automatically generate Forms API & other big array documentation
Current proposal for property documentation
In the current FAPI reference, each Property has its own documentation section, with Description, Values, a Usage example, and a list of which elements use that property.
Our current idea on how to replace this is that we probably only need a data type and a one-paragraph description. [Presumably, the API module will be able to generate a "functions that use this property" page, and the "elements that use this" list. And we decided property descriptions didn't need to be extremely extensive.]
With that in mind, we can define new @-tags for properties, and add them to documentation headers like this:
* @render_property_all string #type
* The type of element to render, as defined in a hook_element_info()
* implementation. Default property values for this element type from
* hook_element_info() are added to the $elements array.
This consists of:
- A tag, one of:
- @render_property_all - properties used by all render elements, which should be added to the documentation of drupal_render().
- @render_property_common - properties used by some, but not all, render elements, which should be added to the documentation of drupal_render().
- @render_property_internal - properties used internally by the rendering system, which should be added to the documentation of drupal_render().
- @form_property_all - properties used by all elements that are part of forms, which should be added to the documentation of drupal_build_form().
- @form_property_input - properties used by all form input elements, which should be added to the documentation of drupal_build_form().
- @form_property_common - properties used by some, but not all form elements, which should be added to the documentation of drupal_build_form().
- @form_property_internal - properties used internally during form processing, which should be added to the documentation of drupal_build_form().
- @render_property - properties used specifically by one render/form element, or whose standard definition is overridden by a render/form element. Documentation is within the render/form element documentation (see below).
- Data type - same convention as providing @param/@return/@var data types.
- Property name, starting with #
- Description (one paragraph, indented)
Current proposal for element documentation
There is still some disagreement on what to do about element documentation. Basic needs:
- Not limited to one paragraph -- we want to be able to use @code, @see, etc. and multiple paragraphs in element documentation.
- Some way to list which properties are used by the element (although we wouldn't want to have to list all of the common-to-all properties -- we just want to list the specific properties for this element, and the properties whose definitions are non-standard).
Thus, the documentation block should look something like this:
* Form input element for a select list.
* Optional longer description would go here.
* @form_input_element select
* #empty_option, #empty_value, #multiple, #options
* @render_property int #size
* The number of lines in a listbox-style select element.
* @see function_that_uses_this_element()
* @see theme_select()
* @ingroup elements
- First line description and optional longer description (as in function docs)
- After the description, include a line telling what type of element it is: @input_element (for form input elements only) or @render_element (for all other elements), giving the machine name of the element you are documenting.
- After the @input_element/@render_element tag, use the @render_properties tag to list which _common form/element properties this element makes use of in its default rendering (if any). Do not include *_all, *_input, or *_internal properties.
- For any properties that either have documentation that is different from the standard, or that are specific to this form/render element, use the @render_property tag to document the specific meaning of that property on this element (see properties section above).
- Include @see references to one or more good illustrative examples of where this element is used, and to theme and preprocess functions. [Presumably, the API module will be able to generate a "functions that use this element" page.]
- Include @ingroup elements [exact group name TBD!!] to indicate this is an element to be included in the Form/Render API elements list.
Where to put the element documentation???
The main remaining question is where to put this documentation block. Proposed ideas:
- As part of the documentation block for the theme or preprocess function for this element. We have pretty much abandoned this idea, because it would not be possible to separate out the documentation for this function and the documentation for the element. [Proposals: comment #1, #8]
- Immediately before the declaration of the element inside of a hook_element_info() implementation. This idea ran into some opposition, because we don't normally have /** */ documentation blocks within functions, and it causes some problems. [Proposals: comment #14. Vehement opposition: comment #19, #28]
- Separating out the individual element declarations in system_element_info() into their own functions, and putting the element documentation there. Other hook_element_info() functions that only define a single element could have the element documentation added to that function header directly. This runs into the same problems as putting the element documentation into the theme function, but it's not quite as bad, since these small functions do not have any purpose except to declare an element, so there is not much function documentation to separate out from the element documentation. [Proposal: comment #21]
- Putting the element documentation blocks into a separate file (system_elements.api.php or something like that). The disadvantage of this idea is that it makes the documentation for elements separate from the declaration/code, and this leads to the documentation not being updated (as has been our experience with having hook documentation in .api.php files).
A. Decide on and adopt a standard for the documentation headers. Deciding where to put the headers for elements is the one remaining question to be answered (see Proposed Resolution section above).
B. Make patches for Drupal 8.x and 7.x, to move the documentation currently in the FAPI reference document into the Drupal Core code as documentation headers.
C. Make the API module parse and display this documentation information (separate issue #100680: Automatically generate Forms API & other big array documentation).
User interface changes
No Drupal UI changes.
No Drupal API changes.