qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Justin Ross (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache Qpid > Project Inquisition
Date Wed, 07 Aug 2013 15:27:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/en/2176/1/21/_/styles/combined.css?spaceKey=qpid&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/qpid/Project+Inquisition">Project
Inquisition</a></h2>
    <h4>Page  <b>added</b> by             <a href="https://cwiki.apache.org/confluence/display/~justi9">Justin
Ross</a>
    </h4>
         <br/>
    <div class="notificationGreySide">
         <p>'Project Inquisition' is an effort to improve the proton API docs.  Its
initial focus is on the Messenger, Message, and Data APIs.</p>

<p>Each important API member (method, property, class) should answer these important
questions:</p>

<ul>
	<li>What does it do?  What is the intent?</li>
	<li>What arguments are there, and how do they affect behavior?</li>
	<li>Which arguments are required, and which optional?</li>
	<li>What related properties are there, and how do they affect behavior?</li>
	<li>What is the return value or result?</li>
	<li>What does success look like?</li>
	<li>What are the attendant error conditions?  When do they occur?  How are they reflected
in the result?</li>
	<li>Where does it fit in the lifecycle of its containing object?  For instance, are
there times when its illegal to call it?</li>
	<li>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.</li>
</ul>


<p>And surely there are more questions.  Please amend this list as you find them.</p>

<p>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.</p>

<p>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.</p>

<h2><a name="ProjectInquisition-Anexample"></a>An example</h2>

<p><a href="http://people.apache.org/~jross/misc/api-comparison.png" class="external-link"
rel="nofollow">Messenger Send</a></p>

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

    </div>
    <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;" class="grey">
                        <a href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=qpid">Stop
watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action">Change
email notification preferences</a>
</div>
       <a href="https://cwiki.apache.org/confluence/display/qpid/Project+Inquisition">View
Online</a>
              |
       <a href="https://cwiki.apache.org/confluence/display/qpid/Project+Inquisition?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
           </div>
</div>
</div>
</div>
</div>
</body>
</html>

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message