Document in views.api.php for each hook in which include file they can be placed

Nikolas Haliotis → made their first commit to this issue’s fork.

CC failure

Change matches IS and passes tests now.

Removed implementation details for the field hooks and added the implementation details to the missing hooks.

Thanks @quietone, I had also gotten hung up on the field hooks when reviewing this. Here's what I had documented:

• query_substitutions
  Invoked from src/Plugin/views/query/Sql.php
• form_substitutions
  Invoked from src/Form/ViewsFormMainForm.php
• Invoked directly from ViewExecutable:
  • views_pre_render
  • views_post_render
  • views_pre_build
  • views_post_build
  • views_pre_view
  • views_pre_execute
  • views_post_execute
• Also in ViewExecutable:
  

      // Let modules modify the query just prior to finalizing it.                
      $this->query->alter($this);
  

  ...which gives us views_query_alter.

@Lendude and I also discussed a followup for this. The use of .inc files is archaic, and even in the original issue it was identified that these two magically named include files were bad DX. Their purpose is to avoid loading code that is not needed on a given request, but nowadays we should be able to come up with a better pattern for that with a modern architecture and better DX. To be discussed in the followup. :)

A thought: Should the runtime hooks and the non-runtime hooks furthermore be placed in different phpdoc groups? Documenting it on the individual hooks is good for when someone just looks up the individual hook, but if we add two defgroups, that will also give us a spot to document the "why" of the two different hook categories from the original issue.

We should also perhaps have a second followup to document the field hooks differently (with their own docs and in their own third group).

Updating the remaining tasks with the above.

So my understanding is that we want the views.api.php file to be organised like so:

-> a doc block at the start with documentation on the views
-> all the hooks that are relevant
-> a doc block with the documentation for the runtime hooks
-> all the hooks that are relevant
-> a placeholder doc block for the field hooks with a TODO
-> all the field hooks

Also there should be a task about the documentation of the field hooks after this, right?

Thanks @Nikolas Haliotis for looking into this. :) Crossposting my remarks from #contribute in Drupal Slack:

I was referring to the phpdoc @defgroup tags: https://www.drupal.org/docs/develop/standards/php/api-documentation-and-... →

Currently, there are two @defgroup in views.api.php: A views_overview group and a views_plugins group. I was suggesting maybe creating two new groups, a views_execution_hooks and a views_something_else_hooks (needs a proper name). Each of those groups could have high-level explanations of the differences between the two kinds of hooks and why they get placed where they do.

I do think the added paragraph on the individual hooks is also still useful, so we can leave it there. However, we would remove the changes to the two field hook definitions from the patch, and then have a followup to see if they should be documented in some other way based on how other field hooks are documented elsewhere (possibly an @ingroup or something else, but we don't need to figure it out in this issue, just create a separate issue before it's RTBC).

Hopefully that helps!