Rethink param "show docs"

[Preetam]

We should be able to check for showdocs=true in a middleware handler, if that makes sense.

[John Berryman]

I don't understand where you're going with this one.

[Preetam]

@xaprb, do you have any thoughts on this?

[xaprb]

This refers to some functionality for a non-open-source REST framework we
use internally at VividCortex, which has the ability to respond with
information about what endpoints exist and what parameters they accept. I
haven't looked at Siesta enough to know -- does it handle things similarly?
Or could/should it? Is that your question Preetam?

[Preetam]

I was thinking about implementing a middleware function to handle generating the docs for the params. I don't think it's actually possible to do before a route handler since each has a different set of parameters.

[Preetam]

At this point, I think there's enough in the package itself to support this without any changes.

Here's what one could do:

1. Check if the user requested usage documentation at the beginning of a chain.
2. Create a map to hold the documentation for all of the parameters.
3. Run through the chain. Each handler would update the documentation map using the output from params.Usage, since each handler can have its own set of parameters. It's important to make sure each handler only updates the documentation map and does nothing else.
4. Send the output back to the user

On a related note, I'm not really a fan of having the magical showdocs parameter. I think we should get rid of that. The rest can be done with simple context variables and params.Usage().

Ping @gkristic.

[Gustavo Kristic]

Sounds good to me. (For future reference: see also this.)

[Preetam]

We know how to do this now.