On Mon, Apr 19, 2010 at 6:37 PM, Jonathan Robie <[email protected]> wrote: > 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.
Understand your concern here. As you suggested we could take these code snippets from working code some where in the source tree. However I hope the reservation example will contain the code we need for the docs. > > >>>> 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] > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/ --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:[email protected]
