-
Notifications
You must be signed in to change notification settings - Fork 498
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs: full review of Hook documentation #646
Conversation
Also related to #321 |
Hmm, still on the fence about this one, as I'm not yet sure whether the documentation for the optional |
Those are two separate issues to address though. The documentation is issue 1, at least with this PR it would be "hook complete", which is much better then it is now. Deciding whether or not to always pass Generally speaking I'm in favour of John's suggestion and would recommend for hooks to have the same number of arguments every time they are called, however, making this change now could be considered a breaking change as functions which "hook in" very likely will need updating (callbacks may have a different default value set - |
Inspired by issue 220, I've: * Verified that all hooks listed in the documentation still exist in the codebase. * Verified the parameters for all hooks listed in the docs with the actual parameters in the hook calls in the codebase. * Verified that all hooks in the codebase are listed in the Hooks documentation page, with the exception of the `transport.internal....` hooks. Note: * The hook descriptions for the added hooks can probably use further improvement. I wasn't always sure how best to describe the hook event. * The ordering of this list looks to be a loose "requests hooks, curl hooks, fsockopen hooks and those in the order they are called" order. With some of the additional hooks, it wasn't always clear where to place them within this loose order, so suggestions to improve the order are welcome. Also note the the naming of the `request.progress` hook seems inconsistent. I do understand why the hook uses `request` instead of `requests`, but this may be something to revisit at a later point in time.
8a11961
to
807166b
Compare
Inspired by issue #220, I've:
transport.internal....
hooks.Note:
With some of the additional hooks, it wasn't always clear where to place them within this loose order, so suggestions to improve the order are welcome.
Also note that the naming of the
request.progress
hook seems inconsistent. I do understand why the hook usesrequest
instead ofrequests
, but this may be something to revisit at a later point in time.