2 files changed, 45 insertions, 16 deletions
diff --git a/doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp b/doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp
index 257251512d..3a80d740ff 100644
--- a/doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp
+++ b/doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp
@@ -190,38 +190,46 @@ int main(int argc, char *argv[])
 
 void completeExample()
 {
-    //! [Complete example]
     // Create the input vCard
+    //! [Complete example - create]
     QBuffer input;
     input.open(QBuffer::ReadWrite);
     QByteArray inputVCard =
         "BEGIN:VCARD\r\nVERSION:2.1\r\nFN:John Citizen\r\nN:Citizen;John;Q;;\r\nEND:VCARD\r\n";
     input.write(inputVCard);
     input.seek(0);
+    //! [Complete example - create]
 
     // Parse the input into QVersitDocuments
+    //! [Complete example - read]
     // Note: we could also use the more convenient QVersitReader(QByteArray) constructor.
     QVersitReader reader;
     reader.setDevice(&input);
     reader.startReading(); // Remember to check the return value
     reader.waitForFinished();
+    QList<QVersitDocument> inputDocuments = reader.results();
+    //! [Complete example - read]
 
     // Convert the QVersitDocuments to QContacts
-    QList<QVersitDocument> inputDocuments = reader.results();
+    //! [Complete example - import]
     QVersitContactImporter importer;
     if (!importer.importDocuments(inputDocuments))
         return;
     QList<QContact> contacts = importer.contacts();
     // Note that the QContacts are not saved yet.
     // Use QContactManager::saveContacts() for saving if necessary
+    //! [Complete example - import]
 
     // Export the QContacts back to QVersitDocuments
+    //! [Complete example - export]
     QVersitContactExporter exporter;
     if (!exporter.exportContacts(contacts, QVersitDocument::VCard30Type))
         return;
     QList<QVersitDocument> outputDocuments = exporter.documents();
+    //! [Complete example - export]
 
     // Encode the QVersitDocument back to a vCard
+    //! [Complete example - write]
     // Note: we could also use the more convenient QVersitWriter(QByteArray*) constructor.
     QBuffer output;
     output.open(QBuffer::ReadWrite);
@@ -229,11 +237,8 @@ void completeExample()
     writer.setDevice(&output);
     writer.startWriting(outputDocuments); // Remember to check the return value
     writer.waitForFinished();
-
-    // Read the vCard back to a QByteArray
-    output.seek(0);
-    QByteArray outputVCard(output.readAll());
-    //! [Complete example]
+    // output.buffer() now contains a vCard
+    //! [Complete example - write]
 }
 
 void exportExample()
diff --git a/doc/src/versit.qdoc b/doc/src/versit.qdoc
index 7a9a5ea50b..883515e390 100644
--- a/doc/src/versit.qdoc
+++ b/doc/src/versit.qdoc
@@ -56,20 +56,44 @@ to facilitate the future migration of Mobility APIs into Qt. See the
 namespace impacts on application development.
 
 \section1 Overview
-The Versit API provides a set of methods to parse/read (\l{QVersitReader}) and
-encode/write (\l{QVersitWriter}) Versit \reg documents such as vCards
-(\l http://www.imc.org/pdi/).
-Currently \l{QVersitReader} and \l{QVersitWriter} support
-reading and writing vCard 2.1 and 3.0 formats.
+The Versit API provides a library to convert \l{QContact}{QContacts} to and from
+\l{http://en.wikipedia.org/wiki/Vcard}{vCard} files.
 
-Versit API also provides utilities to import (\l{QVersitContactImporter})
-QContacts from Versit documents and export (\l{QVersitContactExporter})
-QContacts to Versit documents.
+vCards are represented abstract form with the QVersitDocument class.  vCard
+files can be parsed into QVersitDocument form using QVersitReader.
+QVersitDocument objects can be written to an I/O device using QVersitWriter.
+
+\l{QVersitDocument}{QVersitDocuments} can be converted to
+\l{QContact}{QContacts} using QVersitContactImporter.  \l{QContact}{QContacts}
+can be converted to \l{QVersitDocument}{QVersitDocuments} using
+QVersitContactExporter.
+
+Currently \l{QVersitReader} and \l{QVersitWriter} support reading and writing
+vCard 2.1 and vCard 3.0 format documents.  
 
 Versit \reg is a trademark of the Internet Mail Consortium.
 
 \section1 Usage
-\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example
+The following example goes through the process of reading a vCard and importing
+it to QContact format, then exporting and writing it back out.
+
+First, let's create some data to read.  In this case, we create a QBuffer as a demonstration, but
+any QIODevice will work.
+\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - create
+
+QVersitReader can be used to parse a vCard or iCalendar from an I/O device to
+produce a list of QVersitDocuments.
+\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - read
+
+QVersitDocuments aren't very useful to the QtContacts API.  They need to be imported using the
+QVersitContactImporter.
+\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - import
+
+Conversely, QVersitContactExporter can be used to convert from QContacts to QVersitDocuments.
+\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - export
+
+To complete the exporting process, QVersitWriter can be used to write to an I/O device.
+\snippet ../../doc/src/snippets/qtversitdocsample/qtversitdocsample.cpp Complete example - write
 
 \section1 Main Classes
 \list