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 behaviour. 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. Regards, Rajith > William > >> >> Rajith >>
