'Project Inquisition' is an effort to improve the proton API docs. Its initial focus is on the Messenger, Message, and Data APIs.

Each important API member (method, property, class) should answer these important questions:

• What does it do? What is the intent?
• What arguments are there, and how do they affect behavior?
• Which arguments are required, and which optional?
• What related properties are there, and how do they affect behavior?
• What is the return value or result?
• What does success look like?
• What are the attendant error conditions? When do they occur? How are they reflected in the result?
• Where does it fit in the lifecycle of its containing object? For instance, are there times when its illegal to call it?
• Is it tightly coupled to any other members? Is it symmetric with another? For example, in some APIs 'begin', 'commit', and 'rollback' form one logical group of methods for controlling transactions.

And surely there are more questions. Please amend this list as you find them.

The work here is to walk through the API members of two language implementations of the messenger API, and for each corresponding member to check if both are answering these questions. When you discover gaps, expand the API doc using the native comment format for the language. I recommend using python's documentation as the master, so each new pair for evaluation would be python and any other language. Each time something is found in a non-python language, it must be reflected into the python api.

In some cases, you will likely run into API differences. Sometimes those will be well motivated ones, due to language differences. In other cases, however, it's just down to uncontrolled variation. Keep notes! Keep notes on this page even. We want to review each one and decide whether it's a problem.

An example

Messenger Send

• Python's says nothing about a return value. How does one tell if it succeeded? Does it throw any exceptions?
• Python's mentions timeout, but C's doesn't.
• Neither describes specific error conditions.
• Neither points out that nothing will happen if the messenger instance isn't started.