Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Posted by xjm
Problem/Motivation
There are several deficiencies in Views' API documentation:
- While
views.api.phphas 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/@ingroupwere 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@defgroupwrapped 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.
Proposed resolution
- 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.)
Remaining tasks
Related issues
| Comment | File | Size | Author |
|---|---|---|---|
| drupal-8-core-monthly-patch-volume.jpeg | 108.88 KB | xjm |
Comments
Comment #0.0
xjmUpdated issue summary.
Comment #1
hansfn CreditAttribution: hansfn commentedYes, improved Views documentation would really help. I'm trying (for fun) to port Views Send, a Views Form implementation, to Drupal 8. It started with hook_views_api being gone and the views.inc file (in a subdirectory) not being loaded ... Do you plan to document such changes on http://drupal.org/list-changes/drupal or to create a separate page for Views?
Comment #2
dawehner@hansfn
Yeah this changed quite a lot, so I documented the hook_views_api() change in http://drupal.org/node/1875596
Comment #3
xjm@hansfn, see http://drupal.org/list-changes/views. We've started adding the change notifications from 7.x-3.x to 8.x core views there.
Comment #4
hansfn CreditAttribution: hansfn commentedThx, dawehner and xjm, for the quick reply.
Regarding the list of changes in Views, I can't find a general note about how to extended Views classes - for example views_handler_field. (I guess I can look at for example the core user module to get the idea - I already have and I think I have gotten it.)
PS! It seems some of my problem with the lack of documentation was related to the change list. I thought http://drupal.org/list-changes would list everything, but it's only listening core changes (as the title actually says). I'm not sure how I was supposed to find http://drupal.org/list-changes/views ...
Comment #5
xjmWell, the Views change list is also incomplete (we identified a bunch of changes we need to add change notices for at our last sprint). We're planning to really focus on the documentation later in the release cycle. The link to the Views change notices is in the far lower right of the Views project page.
Comment #6
dawehnerThe guide how to write plugins in d8 is probably a helpful start for many general questions: http://drupal.org/node/1637614
Comment #7
hansfn CreditAttribution: hansfn commentedThx again, dawehner and xjm. Looking forward to a D8 version of Views Send ...
Comment #8
hansfn CreditAttribution: hansfn commentedOK, I just tried to add a change notice - get_url has been replaced with getURL - but I wasn't able to select the correct project. Entering "Views" in the project box on http://drupal.org/node/add/changenotice didn't give me a suggestion I could use. Any hints?
PS! Maybe I should make noise somewhere else? I feel I'm abusing this issue now.
Comment #9
dawehner@hansfn
Most functions will be replaced to be camelCase so we maybe need just a big big table.
Regarding entering views, just type it in, it works, even the autocompletion fails.
Comment #9.0
dawehnerUpdated issue summary.
Comment #10
xjmI added #1882558: [META] Document all views plugins types to the summary. If folks are interested in helping with documentation, that's a place to help out now!
Comment #11
LeeHunter CreditAttribution: LeeHunter commentedUser-facing documentation (i.e. the old advanced help content) issue is here: http://drupal.org/node/1892470
Comment #11.0
LeeHunter CreditAttribution: LeeHunter commentedUpdated issue summary.
Comment #11.1
xjmUpdated issue summary.
Comment #11.2
xjmRemoving myself from the author field so that I can unfollow the issue. --xjm
Comment #12
jmarkel CreditAttribution: jmarkel as a volunteer commentedI am removing the Novice tag from this issue because neither of the two remaining tasks are Novice tasks.
I’m using this documentation as a source: https://www.drupal.org/core-mentoring/novice-tasks#avoid