Fully annotate one (or more) example programs

[jernst]

When attempting to write my own code, I started with some of the many (great!) examples you provide. However, there is very little commentary in those examples, making me guess about a bunch of things -- and not all of it is easily findable in the documentation either.

Example: parameter displayListLength. I am guessing it has something to do with reserving a buffer, like for commandListLength, for which it was easier to find documentation -- but I'm not sure.

Suggestion: take one or more representative examples, and annotate every parameter and every call. This would make the life of new developers simpler. Just a thought ...

[phoddie]

Glad the examples are at least somewhat helpful.

The examples are intended to be small standalone apps that exercise a specific feature. The examples are intended to be used with the documentation. They are not intended as tutorials, which seem more like what you suggest. Tutorials would be welcome, of course.

A search of the documentation directory shows an explanation for displayListLength here in the Poco documentation and the corresponding Piu reference here. There are plenty of other references to "display list" in the Poco document. commandListLength does appear to be undocumented. We'll fix that in the Piu documentation.

That said, there are a nearly infinite number of configuration options in embedded programming. The general rule is simple: don't change them if (a) you don't understand them and (b) they aren't causing you a problem. ;) If you encounter a display list or command list overflow error, you'll know which knob to adjust.