Posted by xjm
There are several deficiencies in Views' API documentation:
views.api.php has been updated to Drupal 8, basic explanations for handler plugin types are missing.
- The hook examples need review by an experienced Drupal 8 Views developer; many were updated but some may still be out of date.
- Much of the documentation has not been updated from Drupal 7 (or, in some cases, Drupal 6)...
- All base plugins and handlers need significantly more documentation.
@ingroup were moved around when Views' classes were converted to PSR-0, and as a result some classes are probably missing their
@ingroup, while Views also has the odd pattern at present of having an
@defgroup wrapped around a single PSR-0 class in the base class for a kind of plugin.
- Critical documentation like function and method summaries, parameter documentation, and typehints is widely missing.
- In general, many parts of Views do not conform to Drupal 8 documentation style guidelines.
- Throughout the release cycle, new patches added to Views will be adjusted to core documentation standards defined in the Core documentation gate minimum requirements.
- We will hold a virtual sprint to do general cleanup of the Views API documentation. This sprint will not begin until at least Feburary 2013. There are two important reasons for postponing the sprint until then:
- Documentation cleanup patches often take longer to review than to create, and while they are great contribution opportunities for novices, they also need to be reviewed for their accuracy by an experienced developer. The VDC team needs to focus important features and APIs at this point in the release cycle.
- Documentation cleanups frequently conflict with other patches, because they affect many lines scattered throughout the codebase, in and around actively developed APIs. With a record volume of patches currently being submitted each month, early feature freeze is the worst possible time to force rerolls. (See the graph below, from Dries' blog.)