On Aug 23, 2011, at 12:33 PM, Marek Potociar wrote:
>>
>> Now the bad...
>>
>> At first glance the class hierarchy is ridiculous. The Javadoc will not be very useful to first-time users as the class
>> hierarchy is hard to understand even for somebody that has been working on JAX-RS 2.0 (i.e. me).
>
> That's the natural cost of a fluent API[*]. I would argue that the purpose of a fluent API is to be easy to use by *end
> users*, resemble natural language flow and provide consistent context continuation wrt. given context state so that e.g.
> IDE code completion can benefit from that.
>
> Such API is best described by examples, not as a javadoc merely describing the class hierarchy and list of their
> methods. See here for a good example:
>
> http://google-guice.googlecode.com/svn/trunk/javadoc/com/google/inject/Binder.html
I agree. I've seen other APIs that are quite difficult to explain when in Javadoc form, but pretty straightforward to use in practice. Several collection-type APIs out there with support for map/fold/etc. can result in hairy type definitions (generic type definitions with multiple type variables and type bounds) that are actually quite easy to use.
I came across another instance of this when exploring the client-side validation API (now dropped from our radar) in Section "Direct Binding using Validators" of [1]. The contrast between the method types and the example is quite apparent there.
Personally, I believe code completion goes a long way to help with ease-of-use, and a carefully designed fluent API can really help developers get up to speed quickly.
-- Santiago
[1]
http://java.net/projects/jax-rs-spec/pages/Validation