[META] Views documentation improvements

Created on 2 December 2012, over 12 years ago

Updated 21 February 2025, 3 months ago

Posted by xjm

There are several deficiencies in Views' API documentation:

While 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.
Plugin @defgroup/@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.)

📌 Task

Status

Fixed

Version

11.0 🔥

Component

documentation

Created by

mbkaba22

Live updates comments and jobs are added and updated live.

Incomplete comments

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Comment 3 months ago →
🇳🇿New Zealand quietone
Came across this issue today. I don't see what this is postponed on so normally I would set an issue to 'Active'. However, all the remaining tasks here have been completed, so closing as fixed makes more sense. That is not to say that Views documentation can't be improved, just that this issue is complete. There are existing issues for views to improve documentation as well. Therefor, closing this meta.
Comment 2 months ago →
System Message
Automatically closed - issue fixed for 2 weeks with no activity.

Production build 0.71.5 2024