Notes regarding documentation

[Vittoria Bitton]

Hey Wojtek 👋🏻

We are refactoring our HTTP client to use Req in all our third-party API wrappers :D During the process, I had some thoughts regarding documentation and I would like to have your input on how we might improve it.

I used the README from the Github project, the hex_docs, and the blog posts on Dashbit website. I found that relying solely on hex_docs didn't provide a complete picture.

Both project README and the hex_docs mention:

Virtually all of the features are broken down into individual functions called steps. You can easily re-use and re-arrange built-in steps (see Req.Steps module) and write new ones.

My first impulse was to check the Req.Steps module to see the available steps and they appear as functions right away, but once you go through them, it is all options (keyword args) that should be used in the Req, Req.Request and/or Req.Response modules. So maybe somehow displaying the Req.Steps module to the public docs can be a bit misleading?

Also, there is the append_request_steps/1 function in the Req.Request option but that didn't seem the default for playing around with the steps, there is only one example for debugging the request, but I'm wondering if it would apply to other use cases.

Also, I think would be nice to add all steps options in the Req and Req.Request modules, because what happened for me is that I had to go through multiple places to check all options/steps available. What do you think?

Other things I noticed:

1. Two functions in the Req.Request module that seems interesting but really lacks documentation: request_step/0 and response_step/0 for when it is best applied.
2. For configuring a plug stub for different environments: is this the only way to implement it? If yes, would be worth documenting it explicitly rather than just in the example?

Also, this blog post about SDKs with req gave a good direction of what could be a standard for implementing a "main/base request" for different URLs without repeating code every time in Req.get/post/.... Perhaps something like this can be reflected in the docs as well?

Anyway, I'm eager to contribute and help but some feedback and possible directions could be helpful :D

[Wojtek Mach]

This is great, I'll try to address this soon!