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

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 aside from that:

• 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 hundreds/thousands of lines of 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!

Given that hook_hook_info() is gone and we're moving to completely kill off procedural .inc files and move all hooks to OOP, I think this should probably be "outdated" at this point. Any objections?

Thanks/sorry,
-Derek

I agree, this is most definitely outdated.

Okay, done.

Thanks!

Just wanted to give a quick note that all closed issues now get credit and everyone here has been granted credit for helping with this, thank you!