Nice suggestions actually. I think some of the discrepancy has to do with the 
difference between languages and the idioms that have long been fossilized int 
the different naming conventions. 

Again, all suggestions on proposed look good to me. 

Regards,

-W

On Dec 13, 2012, at 5:37 PM, Justin <jr...@redhat.com> wrote:

> API usability is important and deserves attention.
> 
> Take, for instance, DeliveryState versus Disposition.  That only serves to 
> confuse people.  It's a difference that has no content.  I also think 
> link.drained and link.offered are very unclear.
> 
> I've found the whole process of proposing API review dispiriting.  You can, 
> of course, take it or leave it.  I in no way wish to claim I have better 
> choices.  I only wish to point out things that might deserve more 
> deliberation.
> 
> Justin
> 
> ---
> 
> Endpoint state
> 
>  PN_LOCAL_UNINIT
> 
>    Existing C name:    PN_LOCAL_UNINIT
>    Proposed C name:    PN_LOCAL_UNINITIALIZED
>    Existing Java name: EndpointState.UNINITIALIZED
>    Proposed Java name:
> 
>    One api has the remote-local distinction in one bitset, and one does
>    not.  Is this difference desirable?
> 
>  PN_REMOTE_UNINIT
> 
>    Existing C name:    PN_REMOTE_UNINIT
>    Proposed C name:    PN_REMOTE_UNINITIALIZED
>    Existing Java name: EndpointState.UNINITIALIZED
>    Proposed Java name:
> 
>    Personally, I'm at ease with UNINIT as an abbreviation here
> 
> Types
> 
>  pn_disposition_t
> 
>    Existing C name:    pn_disposition_t
>    Proposed C name:
>    Existing Java name: DeliveryState
>    Proposed Java name: Disposition
> 
>    DeliveryState vs. Disposition.  A good example of a confusing
>    difference.  I have a slight preference for DeliveryState (it's self-
>    explanatory), but matching is the main thing.
> 
>  pn_delivery_tag_t
> 
>    Existing C name:    pn_delivery_tag_t
>    Proposed C name:
>    Existing Java name: [anonymous byte array]
>    Proposed Java name:
> 
>    DeliveryTag?
> 
> Session
> 
>  pn_session_connection
> 
>    Existing C name:    pn_session_connection
>    Proposed C name:    pn_session_get_connection
> 
>    According to Rafi's system, this should have _get_.
> 
> Link
> 
>  pn_link_session
> 
>    Existing C name:    pn_link_session
>    Proposed C name:    pn_link_get_session
> 
> Sender
> 
>  pn_link_drained
> 
>    Existing C name:    pn_link_drained
>    Proposed C name:    pn_link_drain_credit [?]
>    Existing Java name: Sender.drained
>    Proposed Java name: Sender.drainCredit [?]
> 
>    I can't tell what's going on here.  I particularly dislike
>    pn_link_drained and _offered.  They look like predicates but have no
>    return value.
> 
> Receiver
> 
>  pn_link_flow
> 
>    Existing C name:    pn_link_flow
>    Proposed C name:    pn_link_issue_credit
>    Existing Java name: Receiver.flow
>    Proposed Java name: Receiver.issueCredit
> 
>    Consider pn_link_increase_credit, pn_link_issue_credit; working in the
>    word "credit" somehow would help a lot
> 
>  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
> 
> Delivery
> 
>  pn_delivery_link
> 
>    Existing C name:    pn_delivery_link
>    Proposed C name:    pn_delivery_get_link
> 
>  pn_delivery_local_state
> 
>    Existing C name:    pn_delivery_local_state
>    Proposed C name:    pn_delivery_state
>    Existing Java name: Delivery.getLocalState
>    Proposed Java name: Delivery.state
> 
>    "Local" is not used elsewhere for local/remote distinctions
> 
>  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.
> 
> 
> On Thu, 13 Dec 2012, Justin Ross (JIRA) wrote:
> 
>> 
>>   [ 
>> https://issues.apache.org/jira/browse/PROTON-26?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13531571#comment-13531571
>>  ]
>> 
>> Justin Ross commented on PROTON-26:
>> -----------------------------------
>> 
>> That's really not the case.  Rejecting it is fine, but it's mostly gone 
>> undiscussed.  That's partly my fault.  A post to the mailing list with 
>> highlights suitable for inline comments is incoming.
>> 
>>> Engine api naming proposal
>>> --------------------------
>>> 
>>>                Key: PROTON-26
>>>                URL: https://issues.apache.org/jira/browse/PROTON-26
>>>            Project: Qpid Proton
>>>         Issue Type: Improvement
>>>         Components: proton-c, proton-j
>>>           Reporter: Justin Ross
>>>           Assignee: Rafael H. Schloming
>>>             Labels: api
>>>            Fix For: 0.2
>>> 
>>>        Attachments: engine-naming-01.patch, 
>>> proton-engine-naming-proposal-2.pdf, proton-engine-naming-proposal-3.pdf
>>> 
>>> 
>>> See 
>>> https://docs.google.com/spreadsheet/ccc?key=0ArGmVtK1EBOMdEw0bkp4OE5UOWpRRkx3RzVoTjliX0E#gid=0
>> 
>> --
>> This message is automatically generated by JIRA.
>> If you think it was sent incorrectly, please contact your JIRA administrators
>> For more information on JIRA, see: http://www.atlassian.com/software/jira
>> 

Reply via email to