On 14 December 2012 01:02, Weston M. Price <wpr...@redhat.com> wrote:

>
> On Dec 13, 2012, at 6:22 PM, Rob Godfrey <rob.j.godf...@gmail.com> wrote:
>
> > A couple of comments...
> >
> > On 13 December 2012 23:37, Justin <jr...@redhat.com> wrote:
> >
> >> API usability is important and deserves attention.
> >>
> >>
> > <snip>
> >
> >
> >>
> >>  pn_link_drain
> >>
> >>    Existing C name:    pn_link_drain
> >>    Proposed C name:    pn_link_rescind_credit
> >>    Existing Java name: Receiver.drain
> >>    Proposed Java name: Receiver.rescindCredit
> >>
> >>    Consider pn_link_decrease_credit, pn_link_rescind_credit
> >>
> >>
> > Drain *doesn't* rescind credit, or decrease credit, so I'd be -1 on these
> > names. Drain is an indication that the sender should use all available
> > credit, but if insufficient deliveries are available at the sender to use
> > up all the credit, only then should it act as if all credit had been
> > consumed.  At no point is the receiver rescinding credit.
> >
> > <snip>
> >
> >
> >>  pn_delivery_update
> >>
> >>    Existing C name:    pn_delivery_update
> >>    Proposed C name:    pn_delivery_acknowledge
> >>    Existing Java name: Delivery.disposition
> >>    Proposed Java name: Delivery.acknowledge
> >>
> >>    Do calls to delivery.update correspond one-to-one to
> >>    delivery.updated?  The naming implies a symmetry that I'm not sure
> >>    is there.
> >>
> >>
> > I'm -1 on acknowledged. Acknowledgement is one type of update, but not
> the
> > only one. I'm fine with changing the Java to update() to match the C.
> >
> > On things such as bitmaps vs. enums, I think that's just a language
> > convention thing... I don't see a huge need to make such things
> identical.
> > Naming is something that should be aligned between APIs however.
> >
>
> That was the point of the thread, not nit picking certain things.
>
>
I'm not nit-picking - just trying to be being clear that I think some of
the naming suggestions would actually make the API worse. I think drain()
and update( .. ) give a truer sense of the intention of the API call
(though if someone can suggest alternative names that given an even better
sense of the action associated with the call, then I have no issue).

-- Rob

Reply via email to