hook basics need a little improvement

[chx]

Commandfiles may provide hooks in addition to commands. A commandfile method that contains a @hook annotation is registered as a hook instead of a command.

1. The first sentence says "in addition to commands" where the second sentence says "instead of". Which one?
2. I feel it needs to be a mentioned that hooks are loaded on every request. This is weird because normal command classes, as far as I understand these things (which is not that far) are not.

[weitzman]

1. The two sentences are not in conflict. The first is about a file and the second is about a method in that file.
2. All commandfiles in the searchpath are loaded for every request. so yes, all command classes are loaded ... FYI we dont scan the filesystem on every request. Commandfiles that ship with modules are discovered and stored during Drupal container build.

[chx]

Let me take a stab at the intro then:

In addition to the @command methods in command classes above, methods can be defined as "hooks" with the @hook annotation. A method can not be a @command and a @hook at the same time. All classes containing hooks loaded automatically and their hooks are fired during the command processing request flow much like Drupal hooks or Symfony events.

[weitzman]

All classes containing hooks loaded automatically

Thats technically a Drush implementation detail but perhaps ok here. Lets see what @greg-1-anderson thinks. thanks for the improvement.

[greg-1-anderson]

Yes, that is a big improvement, although Moshe is correct -- the annotated command library is not responsible for registering commands. That's done by Robo / Drush.

If you added the word "Typically" before "all classes", then the statement would still be correct.