I would say you should document the semantics of the interface and leave out irrelevant implementation behaviours, and that does often include observable behaviours.
If we need to stay backwards compatible to all possible observable behaviours then our implementation will be overly constrained and people might as well just stay with whatever release they are on. Furthermore, documenting all possible observable behaviours will only encourage people to depend on them, so I think you should assume anything you write down is something we're encouraging people to use/depend on and something we have an obligation to at least try not to break going forward. --Rafael On Tue, Mar 5, 2013 at 11:27 AM, Michael Goulish <mgoul...@redhat.com>wrote: > > Wow, I never thought I would have a philosophy question about > documentation. > > Should I be documenting semantics that will be stable across all[1] > releases? > Or observable behavior in the release you, dear developer, have in your > hands right now? > Or, perhaps, both ? > > I'll tell you, as a developer, I would certainly want to know exactly > what's > going to happen when I call put() and send() with this release. > > ------------------------------ > > [1] for sufficiently small values of "all". > > > > > > > What I said was put is *allowed* to send optimistically, not that it is > > required to. It actually did send optimistically in a previous version of > > the code, however I commented that line out. > > > > I would say the documented semantics of put and send should allow the > > implementation the flexibility to do any of the following: > > > > 1) optimistically transmit whatever it can everytime so long as it > > doesn't block > > 2) never bother transmitting anything until you force it to by calling > > send > > 3) anything in between the first two, e.g. magically transmit once > you've > > put enough messages to reach the optimal batch size > > > > The reason for the behaviour you are observing is that we currently do > > option 2 in the C impl, however we've done option 1 in the past (and I > > think we do option 1 still in the Java impl), and we will probably do > > option 3 in the future. >
