[Meta] Correct documentation for 'list' related issues

This meta issue is to help bring Drupal's core code into compliance with the Documentation Standards around the subject of lists (and arrays).

A list is one or more items. In the context of arrays that may be passed to or returned from functions and class methods, some of these elements of the array may be designated as 'optional', while others may be 'required'. Over time, Drupal's Documentation standards regarding lists, arrays and some associated issues have evolved. Partly as a result, numerous Drupal core files presently are inconsistent in their application of these list (array) documentation standards.

This documentation clean-up effort is ocurring in parallel to (but purposely separate from) the 2011 API documentation cleanup sprint. The intent of all is to ensure more consistently (and hopefully better) documented core code for Drupal. Please free to help out with any of the sub-issues listed below or in 2011 API documentation cleanup sprint!! There are sub-tasks for all ranges of experience from Novice to the most advanced.

Examples of malformed list documentation

These issues are listed by ease of resolution and hence those listed earlier have a higher priority (like a weight variable).

1. The documentation list item is indented one, three or four spaces instead of the standard two spaces.

2. In numerous instances, the description of keys for associated arrays use the list patterns \ -'key': \ or \ -"key": \ instead of the standard pattern \ -key: \.

3. The documentation of lists within doxygen blocks throughout core are used primarily in two contexts:

   • $options associative arrays [which themselves are often '(optional)'] that are passed to functions and class methods, and
   • Associative arrays returned from a function or method.

   Some of these associative arrays have elements that are '(required)' and others that are '(optional)'. However, core files are inconsistent in the application of these terms. Examples here include 'Required.', 'Optional.' and 'Optional ...' instead of the documentation standard.

4. No standards yet exist for how the variable type for the 'value' portion of a $key => $value pair is to be documented. As a result, the exisitng code documentation is wildly inconsistent and often missing altogether. See issue #XXXXXXX for more detailed discussion about what the 'best-practice' for this type of list documentation should be.
5. Further searches through the code base for the term \optional\ reveals the other context in which that phrase is used: the specification of optional variables in calls to functions and class methods. Sometimes '(optional)' is well formed. Other examples include '(Optional)', 'Optional language ...', and so on.
6. Approaching the issue of documenting 'optional' variables from the other direction (e.g., looking at the function defintion itself first and then its documentation), it appears that perhaps as many as half of all optional variables in calls to functions and class methods are not presently documented as such.
7. Finally, only within the last few weeks was issue #711918: Documentation standard for @param and @return data types adopted. Already some @param and @return directives with lists within them currently include variable type hinting. The majority do not. In due course, these need to be added, reviewed and committed.

This issue arose as a side issue to #1310084: [meta] API documentation cleanup sprint in #1315886-42: Clean up API docs for includes directory, files starting with A-C. It is not per se part of the narrowly focused API documentation cleanup sprint, but closely related.

Some of these list issues are can be fixed via easy to review 'bulk' patches that require only looking at the patch file itself. Other portions of this meta 'list' documentation focus require both a reviewer and committer to focus on not only the patch itself, but also the application of the patch to the code file (so that one can confirm the accuracy of @param and @return directives). These second type of patches require far more concentration and time. As a result, these latter patches should be smaller in size to facilitate patch creators, reviewers and commiters.

Note: The last item on the above list is the lowest priority and any patches that include variable type hinting will not be backported to D7. Further, variable type hinting patches require careful review of both the documentation and the function itself. Hence, these type of changes are probably not suited for Novices.

Remaining general tasks

• Define how variable types in the values of an associated array should be documented.
• Ensure that the above documentation is addressed in Documentation standards
• Other tasks to be determined.

Sub-issues with easy patches

• #1326574: Correct list stuff in docs for includes/database

• #1333534: Further cleanup for documentation in core/includes files starting with A-G

• #1333538: Further cleanup for documentation in core/includes files starting with H-Z

• Big patch for all of the *.api.php changes - No issue yet

• Files for entity and field stuff ... - No issue yet

• Files for image module. - No issue yet

  • Interweaves with docs-cleanup-2011 sub-issue #1326608: Clean up API docs for image module
• Rest of module * changes - No issue yet

Sub-issues with more focused patches

• #1331534: Lists Documentation: Insert '(optional)' and like in locale and node modules. - Interweaves with other sub-issues:

  • #1326618: Clean up API docs for locale module

  • #1313980: Clean up API docs for node module

• '(optional)' phrase in bootstrap.inc - No issue yet - Interweaves with docs-cleanup-2011 sub-issue:

  • #1315886: Clean up API docs for includes directory, files starting with A-C

• '(optional)' phrase in common.inc - No issue yet - Interweaves with docs-cleanup-2011 sub-issue:

  • #1315886: Clean up API docs for includes directory, files starting with A-C

Lowest priority sub-issues (with patches for variable type hinting)

• #1333474: Variable Type Hinting for bootstrap.inc file

• #1333470: Variable Type Hinting for common.inc file

Related issues

• #1310084: [meta] API documentation cleanup sprint

• #1330854: Update code to conform to literal array standards

User interface changes

None.

API changes

None.