[Qt-interest] Strange comments in Qt-examples (//! [0])

[David Boddie]

Pedro Santos wrote:

> I found some strange comments in the Qt-Example files //! [0] //! [1]
> //! [2] etc.. What do they mean?

They are markers that we use to mark parts of the code for inclusion in the
documentation. For example, in the src/gui/dialogs/qinputdialog.cpp file
at line 438, there is the following command:

    \snippet examples/dialogs/standarddialogs/dialog.cpp 3

This takes snippet 3 from the examples/dialogs/standarddialogs/dialog.cpp
file and inserts it into the QInputDialog class documentation:

  http://qt.nokia.com/doc/4.6-snapshot/qinputdialog.html#details

Ideally, the snippet names should be descriptive, not just numbers, but we
needed to convert hundreds of old inlined code snippets, and assigning
numbers to them all was the easiest thing to do.

For the record, the rationale for this system came partly from the need to
have language-neutral code snippets. This was used extensively in the Qt
Jambi documentation.

There were other factors that influenced the use of a marker-based system.
These included problems with non-working \code ... \endcode snippets in the
documentation and the brittleness of the \skipto ... \printuntil mechanism
previously used to quote example code.

David
-- 
David Boddie
Senior Technical Writer
Nokia, Qt Development Frameworks