On Mon, Apr 19, 2010 at 1:15 PM, Jonathan Robie <[email protected]> wrote: > 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.
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. >> 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. > * Request / response The only difference here is the use of reply-to ! > * Flow control This is just a one or two liner is python and c++ and config in JMS. I don't think you need it needs it's own example. > * ...... 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. I would hope the reservation example will do this for us. > 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. 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. >> 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] > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/ --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:[email protected]
