On 04/19/2010 12:58 PM, Rajith Attapattu wrote:
Just to add to the above,
I may be repeating certain things from my previous email, but I think
it's important context to understand this email on it's own.
Examples is an overloaded term.
I think we try to do **too many** things with our examples.
1. Use as an intro to the project and a quick getting started guide.
2. Use as a basis for demonstrating certain qpid concepts.
3. Use as a basis for the tutorial (that goes beyond a getting started guide)
I think 1-3 fit together cleanly. I think the examples should illustrate
the basic "recipes" for the API.
4. Use as a basis for demonstrating interoperability
5. Use as a basis for interoperability testing.
I think this needs to be much more extensive than what we can do with
the examples, and will probably involve code that is much less readable.
Getting Started and Tutorial
---------------------------------
- The getting started guide and tutorial could be combined to reduce the effort.
And the Hello World example is a really nice way to introduce the
project and then move to the rest of the topics in the tutorial.
I agree here - and I think a lot of what we're discussing is what "then
move on to the rest" looks like.
- We need to use code snippets from outside of our examples. We can't
write examples that touch everything.
I think we should start with a "recipe book" along the lines of the
bullet point lists that we currently have in our epydoc or doxygen. In
general, those recipes should be illustrated in the examples. In
general, any code or script that occurs in the documentation should be
part of a program that is actually tested.
Demonstrating Concepts
------------------------------
- These are runnable pieces of code.
- These should be,
- nice little utilities like drain or spout
- something dirt simple like the Hello World example
- scripts that help run one of the above using authentication, ssl etc..
- If they are natural candidates for showing interoperability then so
be it. However interoperability should not be the primary goal.
I would add examples for things like these:
* Map messages
* Request / response
* Flow control
* ...... etc .....
I would like to have code that is easily integrated into documentation
with a simple cut-and-paste. In most cases, that doesn't mean including
the whole program, just the few liens that we need.
See http://www.ibiblio.org/jwrobie/blog/?tag=python-messaging-api for an
example of this.
We've integrated that into epydoc, and a similar list is integrated into
our doxygen. I think a "recipe book" like this in each language is a
good "next step" after the stuff that's in the new messaging API tutorial.
Demonstrating Interoperability
-------------------------------------
- Perhaps the "reservation example" can be developed into a nice
little application that can demonstrate interoperability sufficiently.
- Demonstrating interoperability is not just a Hello World program or
sending a map full of primitives !
But we clearly need one test program that sends every possible data
type, and another that receives every possible data type, implemented in
each language. We need to know what works and what does not work.
Interoperability testing.
----------------------------
- Using simple examples as a means of testing interoperability is
woefully inadequate.
(All though I agree something is better than nothing, we need to
move forward from this mind set)
- This should be a separate suite of tests to sufficiently tests a
wide range of aspects.
I think Rupert starting something along this lines, but not sure
what the current status of it.
Agreed - see above. But we might want to start with a list of things
that need to interoperate, it's not just data types.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
