Posted by xjm

Problem/Motivation

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.

Proposed resolution

  1. Throughout the release cycle, new patches added to Views will be adjusted to core documentation standards defined in the Core documentation gate minimum requirements.
  2. 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.)
      drupal-8-core-monthly-patch-volume.jpeg

Remaining tasks

Related issues

Files: 
CommentFileSizeAuthor
drupal-8-core-monthly-patch-volume.jpeg108.88 KBxjm

Comments

Issue summary:View changes

Updated issue summary.

Yes, 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?

@hansfn
Yeah this changed quite a lot, so I documented the hook_views_api() change in http://drupal.org/node/1875596

@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.

Thx, 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 ...

Well, 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.

The guide how to write plugins in d8 is probably a helpful start for many general questions: http://drupal.org/node/1637614

Thx again, dawehner and xjm. Looking forward to a D8 version of Views Send ...

OK, 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.

@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.

Issue summary:View changes

Updated issue summary.

I 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!

User-facing documentation (i.e. the old advanced help content) issue is here: http://drupal.org/node/1892470

Issue summary:View changes

Updated issue summary.

Issue summary:View changes

Updated issue summary.

Issue summary:View changes

Removing myself from the author field so that I can unfollow the issue. --xjm