[meta] Make API module generate Form API documentation

Migrated issue

Reported by: merlinofchaos

Problem/Motivation

Our large array documentation, especially the Form API Reference and the needed but nonexistent Render API documentation are pretty much unmaintainable, and not as usable as they could be.

Problems:
- The documentation is not with the code (different repository even!), so updates to the code do not result in updates to the documentation. This results in errors, omissions, and lack of keeping up with the code.
- The document is a huge HTML page, which is difficult to edit (especially due to some code formatting problems).
- The cross-references in the document are maintained by hand, so are subject to error and incompleteness.

Proposed resolution

1. Document form/render elements in the Drupal Core code directly. Standards for how to do this are being discussed on a separate issue:
#1617948: [policy for now] New standard for documenting form/render elements and properties

2. This issue: Parse this in-code documentation to generate a form and render element/property reference in the API module (see below for details).

Remaining tasks

1. Decide on the coding standard for documenting form/render elements/properties in code on #1617948: [policy for now] New standard for documenting form/render elements and properties.
2. Patch the Drupal Core code to adhere to that standard on that issue or child issues.
3. (this issue) Update the API module so it parses and displays the information (see section below for details).

Details of API module parsing and user interface changes

This summary section was written with a particular decision on the parent issue in mind... will need revision when that decision is arrived at

1. Parse additions:

a) Find doc blocks within hook_element_info() implementations, and parse them as element documentation.

b) Find property docs tags within drupal_render() and drupal_build_form() [or perhaps other spots] and parse them out. They need to be displayed both within those functions and within the FAPI reference area.

c) When a render array is encountered in code, keep track of links/references. For example, a string '#xyz' in code should become a link/reference to the #xyz property, and if possible, a line like

   '#type' => 'element_type',

should become a link/reference to the element.

2. Display

a) Make a page for each element. These should contain:
- Short and long description, plus a See Also section of the docs had any @see tags.
- Element type (whether it's a render element or a form input element).
- A section showing the specific element properties (with property descriptions).
- Links to pages (or anchors within the full listing page?) showing the properties shared by all render elements, all elements used in form arrays, etc. If the element is a form input element, there would also be a link to the page/anchor where the form input properties are listed.
- Similar to the "functions that call this" on a function page, a link to "Functions that use this element" and a separate link to "string references" [there would be some overlap, but the "functions that use this element would be specifically lines that say '#type' => 'element_type')].
- A link back to the specific hook_element_info() implementation where this element was declared/documented.

b) Make a page for each property. These should contain:
- Description
- Type of property (telling whether it's a common-to-all render property, a property that applies only to form input elements, etc.)
- List of elements that use this property, with the element short descriptions
- If there are elements that have overridden this property with their own description, a section showing their descriptions with a link to those elements.
- Link to a page showing all references to the property
- Link back to the function (drupal_render() or drupal_build_form() or whatever) where this property was declared/documented, for the "common" properties, or a link to the hook_element_info() for the "specific" properties.

c) In code, text identified in 1(c) above will turn into links to the element/property.

d) Element list page - a page listing all the elements with their short descriptions, with a separate section for the form input elements, and the rest in the generic render element list. Or these could be two separate pages?

e) Property list page - a page listing all of the properties with their descriptions, separated out by property type. Or these could be separate pages per property type?

f) We could generate a matrix of properties vs. elements like we have in the current API reference... If we do that, I would say we should restrict it to just the "common-to-some" properties (including the common-to-all ones would be kind of silly. Maybe this matrix would belong on the Property list page, in the "common-to-some" section?

API changes

A new standard for form/render elements/properties documentation would be adopted and adhered to by the Drupal community.

Previous issue summary

This is the summary of this issue by @jhodgdon as of #58 .

The problem described in this issue is that our large array documentation, especially the Form API Reference and the needed but nonexistent Render API documentation are unmaintainable, and also poorly maintained and not as usable as it could be. This issue is about creating a new way to generate the Form API doc and documents of its type.

Desirable Requirements

  1. Easy to edit, unlike the current document.
  2. In the Drupal code base, maintained by patches, so it can get updated with the patch that changes the code.
  3. Parseable by the API module (see #13 for notes on that)
  4. (#15, #16) Keep the doc and the definitions as close to each other as possible in the code, so people remember to patch the doc. As a note, the code that defines form elements and properties is: hook_elements/hook_element_info; process, preprocess, and theme functions [these define which properties are used to theme each element]; and examples from existing form builder functions.
  5. (#28) Ability to define descriptions/doc for both elements and properties, and examples for both elements and properties. So both need to have doc headers/files/whatever.
  6. (#28) Cross-referencing of examples/properties should only be defined in one place (otherwise it will conflict or not be up to date), and probably on properties, with the ability to say "ALL" (e.g. everything uses the #process property). Cross-reference table generated automatically by API module.
  7. #34 outlines the desired end product

Suggested Implementations

  1. #33 - Leave it as it is, but move it into the Handbook
    Advantages: No repository access needed for editing
    Disadvantage: It's still impossible to maintain/edit, separate from the code, not patchable
  2. #57 - Use Drupal, node references, and Views to build the document
    Advantages: Sounds like it would be easy to edit.
    Disadvantages: Separate from the definitions, changes cannot be done in patches, not part of API module
  3. #2 - .info files
    Advantages: In the code base, we have code in Drupal for parsing .info files
    Disadvantages: Tons of little files would result, separate from the definitions, not similar to how we do other documentation (new thing to learn, new thing for API module to parse)
  4. #7 - make things that look more or less like PHP class definitions
    Advantages: In the code base, API module already parses classes
    Disadvantages: Separate from the definitions
  5. #35 & #36 (see also comments in #48 ) - element headers in hook_element_info, properties defined in element_properties.api.php
    Advantages: Some information could be automatically parsed by API module from code (such as defaults), doc for elements is with the code, uses familiar syntax, API module shouldn't have trouble parsing it
    Disadvantages: Doc for properties is in a separate file (not sure how to get around that anyway)

Conclusion

@jhodgdon remains in favor of something like #35 & #36 (probably because she proposed it), making sure that everything in #34 can be generated from the doc.

Can we move forward and make this a concrete proposal? I think the next step would be to take a subset of system_element_info() and add doc headers to it, and make a sample element_properties.api.php, and also make sample desired output, and solidify that into a proposal. Obviously, drumm would need to buy in to say "This can be done within the API module", and everyone else would need to buy in and say "it's clear and easy how to maintain this as a coder", and "the output is what we need".

Original report by merlinofchaos

We desperately need to be able to document forms api in API.module. And as we move forward, the new nodeapi stuff is going to need this sort of documentation as well.

I believe we need a way to document that's similar to our existing hook structure. But instead of using functions, we use something that isn't exactly PHP code

Something like?

<?php
/**
 * Control the size of a Forms API widget.
 *
 * has meaning for: textfield, textarea, foo
 */
$api_key = "#size";
?>

Note: this is just a napkin drawing, so to speak. I haven't thought this through, but I'd like to get some discussion going on this, because I see the difficulty in documenting forms API and other API like it to be a very serious impediment to developing Drupal. I'm constantly forgetting specifics and have to look in code to figure stuff out. That shouldn't be the answer we give people.

Related issue: Issue #2596821

Related issue: Issue #2599798

Related issue: Issue #839550

Related issue: Issue #2191525

Related issue: Issue #2603818

Related issue: Issue #1617948

Edited by drupalbot