Plan for Improving Engine API Documentation, and Request for Suggestions, Etc.

[Michael Goulish <mg...@redhat.com>]

Hello, Proton List!

I'd like to take a whack at adding to the documentation
of the Proton Engine API, and I'd be happy to hear any
relevant suggestions, advice, opinions, speculation, calumny,
slander, warnings, desires, requests, demands, tall tales,
theories, predictions, personal experiences, or amusing
anecdotes that anyone might wish to share.  
In that order.


My plan is to attempt documentation of the functions that
are mentioned in Rafi's excellent UML diagram:

   https://cwiki.apache.org/confluence/display/qpid/Proton+Architecture

&& that are not already documented, && that are in the
public interface ( engine.h )


As I work on those functions, I will write little examples,
minimal and focused on one function at a time wherever
humanly possible.  I will probably start with some kind of
Absolutely Minimal Hello World, then use that as a template
to show off other functions.  These examples are for myself,
but if they seem useful I will show them to you and see if
they ought to be published somewhere.


Here is the initial list of functions.  After this I will
go after whatever other functions are in the engine.h file
that are not totally glaringly obvious, like pn_return_char_ptr().
( I made that one up... )


    pn_condition_clear
    pn_condition_is_set
    pn_connection_reset

    pn_delivery_buffered
    pn_delivery_clear
    pn_delivery_readable
    pn_delivery_settled
    pn_delivery_updated
    pn_delivery_writable

    pn_error_clear
    pn_error_set

    pn_link_available
    pn_link_credit
    pn_link_get_drain
    pn_link_is_receiver
    pn_link_is_sender
    pn_link_queued
    pn_link_drain
    pn_link_draining
    pn_link_flow
    pn_link_recv
    pn_link_set_drain
    pn_link_drained
    pn_link_offered
    pn_link_send

    pn_session_incoming_bytes
    pn_session_outgoing_bytes

    pn_terminus_copy

    pn_transport_unbind