On 04/19/2010 01:32 PM, Rajith Attapattu wrote:
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.
I understand the concern here. But we can't write examples that use
every functionality out there.
Perhaps the reservation example could help here to a certain extent.
But writing examples for the sake of it does not add any value.
We may be talking past each other.
I think that the code samples in the documentation should be part of a
program that is tested so we know that they continue to work as the
software changes.
That doesn't mean we need a separate examples directory for each code
sample. Another approach might be to add to the test directory, perhaps
using program names that indicate where an example is used in the
documentation. But I don't like dry code in examples, and errors can
creep in if we edit too much to make a code snippet easy to read when we
drop it into the documentation.
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
What exactly is different here that is not covered in the drain and
spout examples?
Specific code snippets from there and outside can be used here to show
the finer points.
And where do those code snippets exist in a place that is tested as the
code base changes?
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.
We certainly do !
And my point is that this shouldn't be an example and nobody is
interested in seeing such an example.
This is better handled via an interop testing framework and interop
testing framework has more far reaching mandate than a simple example.
We might well want tables that show how these data types map into the
native data types of the various languages we support. But I agree, this
is not an example that would show up as source code in the documentation.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
