Make callback defs types less restrictive

[ryanwinchester]

This builds on PR #363 and probably fixes #327

Examples

I used the format

@callback post(url | term, body | term, headers | term, options | term)

when I could have used a simpler

@callback post(term, term, term, term)

for the sake of code as documentation, but we can just use the simpler version if you prefer.

Reasoning

The reasoning behind these changes is that you really can pass anything in as long as your process_* override returns the proper type.

See the return type:

@spec process_request_body(any) :: body
def process_request_body(body), do: body

[ryanwinchester]

An alternative approach would be to add | any to the request struct's property's types

[edgurgel]

@ryanwinchester I like the any approach! 👍 Thanks again for all the PRs :)

[ryanwinchester]

@edgurgel moved it to request struct properties' types

[edgurgel]

now that I'm reading this we will accept any for the result of process_request_url right? 🤔

[ryanwinchester]

Technically we want anything that implements String.Chars protocol (i.e. can work with to_string/1), but we can't really spec for protocols, so... we're kinda forced to give suggestions, and then include any on the end, imo

Same could be said for some of the other properties, too.

For example the :body we can expect {:stream, enumerable} but can't really spec for the Enumerable protocol, so... any :/

Anyways, they can technically pass any where any of the properties have an associated process_x function and they implement it and return the expected type.

We could make it more obvious if we do:

@callback process_request_url(any) :: url

@spec process_request_url(any) :: url
def process_request_url(url), do: process_url(url)

instead of

@callback process_request_url(url) :: url

@spec process_request_url(url) :: url
def process_request_url(url), do: process_url(url)

(even though they'd really be the same effect in the end, it's just visual)

Thoughts?

[ryanwinchester]

@edgurgel I think it's either this or telling people to cast to string first and close #327 (and possibly tag wontfix)

[edgurgel]

Oh I agree with any for the input. I'm wondering about the return being url as any is also acceptable 🤔

[ryanwinchester]

@edgurgel with this change url includes | any ;)

So really we can put either, but i feel like using url in the return conveys the intention better, even though it doesn't really matter

[ryanwinchester]

However, I'm fine either way, just let me know which you want and where.

[edgurgel]

That's fine then 👍