Sure thing!
First, I would point out that I don't think the name of the method was a
source of confusion in this case. Please correct me if I'm wrong, but my
understanding is that you (quite reasonably) didn't realize you needed a
method to ignore the response body. Whether the method was called
def noResponseHandler : Handler[Unit]
or as it currently appears in the API docs
def >| : Handler[Unit] Ignore response body.
... would have made no difference. No one is discovering the methods in
Dispatch's API docs because javadocs fail to present reasonably advanced
scala libraries (such as, also, the 2.8 scala-lib collections) in a
comprehensible format. Perhaps the 2.8 scaladocs generator will help,
although a lot of people do not seem to like its interface either. What
we really need, for all libraries on all platforms, is of course better
*prose* documentation that walks through all the methods you are likely
to need when starting off. This >| method will certainly be in that
category, when I finally get around to writing such documentation.
But in this case there's an even better technical solution and it
doesn't require any changes to the API: an exception message that
suggests the likely code fix. So I've just committed that to master.
As for the thinking that goes into the Dispatch API, I'm motivated to
make something that is pleasant to use and easy for experienced eyes to
read. I find I can skim symbolic characters a lot faster than alphabetic
tokens, especially the long camel-cased labels that have grown to
dominate Java programming.
For example, if had used "noResponseHandler" instead of >|, then >>
would have been "inputStreamHandler" and I suppose its overloaded friend
would be "inputStreamWithCharacterSetHandler". Imagine if all the method
names that are currently two or three characters were replaced long
names, many ending with the token "Handler" over and over: would the
application code be easier to read?
Maybe my example is exaggerated; I've certainly seen worse in Java but
I'm also sure that someone could do better than that while sticking to
strictly alphabetic labels. My point though is that whether your symbols
are alphabetic or not, there are tradeoffs and pitfalls.
I've put a lot of thought into not just the method names in Dispatch but
the higher level structure, doing the best I can with a particular set
of constraints. And while labels are important, they are literally a
superficial trait. I wish that more people would take the time to try
using the thing, as you have done, rather than dismissing it for being
conspicuously different.
So thanks! I hope you'll continue to give me feedback, as the only way I
can know what trips up new users is if they tell me. I've of course
internalized methods like >| so deeply that they show up in my dreams. :)
Nathan
On 5/12/10 2:28 PM, ssuravarapu [via Databinder] wrote:
> Hi Nathan,
>
> From the standpoint of API design I would like to understand the
> thought process behind the extensive usage of Symbols in the Dispatch
> API. For instance, Why is ">|" preferred as opposed to
> noResponseHandler or something in that lines.
>
> Appreciate your time.
>
> Regards,
>
> - SPS
Locked
