On Thu, Sep 20, 2012 at 4:37 PM, William Henry <whe...@redhat.com> wrote:
> ----- Original Message -----
>> On Thu, Sep 20, 2012 at 4:02 PM, William Henry <whe...@redhat.com>
>> wrote:
>> > Best to look at proton's examples/messenger send.py and recv.py
>> >
>> > That's the only documentation besides messenger.h
>> That's precisely my point.
>> We can't continue to point people at examples to figure out what the
>> API is.
>> Given that we are going to do a bunch of releases, we should spend
>> some time trying to document this API and it's intended behaviour.
>> William, given that you've used it extensively, would you like to
>> take
>> a stab at it?
> I wouldn't say I've used it extensively.  I am getting to know it better 
> though.
> Can we get some suggestions on the format that we'd like to see this 
> documentation in?

William, sorry for the late reply.
You raised a very good question. We will eventually have the API in
several languages from procedural to OO to functional.

While the core of the API remains the same, the look and feel would be
different for each paradigm and/or language.
For example the API in "C" will look different from the API for Java
or Erlang. But they both should provide the same set of features and

So to answer your question, I was thinking about doc that describes
the features and behaviour of the API in plain english.

My concern is that without an authoritative source we will start
having subtle differences between the API's.
A case in point is the current set of Qpid API's. At one stage we
weren't sure which implementation had the correct behaviour.

In the case of the engines, we have only two major implementations
that are tested using the python tests that acts as a functional spec.
But for the client API's, this quickly becomes an issue. I don't think
we could always use a common python test suite.
In such a case a spec could guide the testing for that respective
language which does not have support for python integration.

Also for somebody who wants to write a new language client, such a doc
would be beneficial.

I can buy the argument that we can designate the "messenger.h" as that source.
But then we have to make sure that any changes to the header file is
reflected across all language clients and the documentation in all
those clients are also updated.



> William
>> Rajith

Reply via email to