setters for "fluent" api should not be called setX

[jecollins]

In the Java port, several classes (see Rate for an example) are written in the "fluent" style, where setters can be chained onto the constructor. This improves readability (see RateTests for some examples) and reduces unnecessary verbosity, but it is incompatible with the Java Bean spec, which expects a method called setX to have a void return value.

Two common alternatives are:

• call them withX(), so you can write new Foo().withBar(a).withBaz(b);
• call them simply x(), so you can write new Foo().bar(a).baz(b);

Both of these are nice, but if you need to use a setter later, it looks funny to say myFoo.withBar(42); to set a new value for the bar attribute. Is it better to just say myFoo.bar(42);? Perhaps, but not by much.

[jecollins]

In all or at least most cases, these fluent setters are intended to be used to initialize instances that are then supposed to be immutable. Therefore, we will call them withX().

[jecollins]

All fluent setters are now named as in withX(), and some remained setX() but now return void. The distinction is whether the method was intended to be called at object creation time or sometime later.