URL formation documentation is lacking

[zkessin]

I am trying to build some code to access an api for Nomad. I need to send a delete request to
"/v1/job/<>", the documentation is rather lacking. I think I should be using one of "Capture, ReqBody, QueryParam" or something, but in this page http://haskell-servant.readthedocs.io/en/stable/tutorial/Client.html it is not explained exactly what capture does, or or what "And friends" means.

If there is some more basic documentation I was not able to find it.

In additon the magic generation of functions position :<|> hello :<|> marketing = client api really needs a better explanation

As a developer who is new to haskell (Though has experience with in Erlang and Elm) I found reading the servant tutorial left me rather confused.

[jkarni]

Thanks for the feedback! I think the issue might be that the client part of the tutorial that you linked to ("Querying an API") assumes familiarity with the "A web API as a type" part (first section), where Capture, &c are explained.

If you agree that's the issue, do you have any suggestions about how to make it clearer?

In additon the magic generation of functions position :<|> hello :<|> marketing = client api really needs a better explanation

A complete explanation would be very involved, and require familiarity with quite advanced features of Haskell, but how about changing:

As you can see in the code above, we just “pattern match our way” to these functions. If we try to derive less or more functions than there are endpoints in the API, we obviously get an error.

To:

client api returns client functions for our entire API, and those functions are combined with :<|>. Since our API has three endpoints, client api will have three functions, which we can pattern match on as above. You could say client "calculates" the correct type and number of client functions for the API type it is given (via a Proxy), as well as their implementation.

[zkessin]

that would be better. also maybe putting a link at the top of page to the first page with a note that it should be read first and what things to look out for might help

[phadej]

The tutorial is supposed to be read (or at least skimmed thru) in order. If someone could add notes to each page, it would be great.