Extend apidocs by examples

svn path=/trunk/KDE/kdepimlibs/; revision=1021506

akonadi/contact/addressbookcombobox.h

@@ -35,6 +35,26 @@ namespace Akonadi {
 /**
  * @short A combobox for selecting an Akonadi address book.
  *
+ * This widget provides a combobox to select an address book
+ * collection from the Akonadi storage.
+ * The available address books can be filtered to show only
+ * address books that can contain contacts, contact groups or both.
+ *
+ * Example:
+ *
+ * @code
+ *
+ * using namespace Akonadi;
+ *
+ * AddressBookComboBox *box = new AddressBookComboBox( AddressBookComboBox::All,
+ *                                                     AddressBookComboBox::Readable, this );
+ *
+ * ...
+ *
+ * const Collection addressBook = box->selectedAddressBook();
+ *
+ * @endcode
+ *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4
  */

akonadi/contact/addressbookselectiondialog.h

@@ -34,6 +34,25 @@ class Collection;
 /**
  * @short A dialog to select an address book in Akonadi.
  *
+ * This dialog provides a combobox to select an address book
+ * collection from the Akonadi storage.
+ * The available address books can be filtered to show only
+ * address books that can contain contacts, contact groups or both.
+ *
+ * Example:
+ *
+ * @code
+ *
+ * using namespace Akonadi;
+ *
+ * AddressBookSelectionDialog dlg( AddressBookSelectionDialog::All, this );
+ * if ( dlg.exec() ) {
+ *   const Collection addressBook = dlg.selectedAddressBook();
+ *   ...
+ * }
+ *
+ * @endcode
+ *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4
  */

akonadi/contact/contacteditor.h

@@ -35,6 +35,44 @@ class Item;
 /**
  * @short An widget to edit contacts in Akonadi.
  *
+ * This widget provides a way to create a new contact or edit
+ * an existing contact in Akonadi.
+ *
+ * Example for creating a new contact:
+ *
+ * @code
+ *
+ * using namespace Akonadi;
+ *
+ * ContactEditor *editor = new ContactEditor( Akonadi::ContactEditor::CreateMode, this );
+ *
+ * ...
+ *
+ * if ( !editor->saveContact() ) {
+ *   qDebug() << "Unable to save new contact to storage";
+ *   return;
+ * }
+ *
+ * @endcode
+ *
+ * Example for editing an existing contact:
+ *
+ * @code
+ *
+ * const Akonadi::Item contact = ...;
+ *
+ * ContactEditor *editor = new ContactEditor( Akonadi::ContactEditor::EditMode, this );
+ * editor->loadContact( contact );
+ *
+ * ...
+ *
+ * if ( !editor->saveContact() ) {
+ *   qDebug() << "Unable to save changed contact to storage";
+ *   return;
+ * }
+ *
+ * @endcode
+ *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4
  */

akonadi/contact/contactgroupeditor.h

@@ -32,7 +32,45 @@ class Collection;
 class Item;
 
 /**
- * @short An editor for contact groups.
+ * @short An widget to edit contact groups in Akonadi.
+ *
+ * This widget provides a way to create a new contact group or edit
+ * an existing contact group in Akonadi.
+ *
+ * Example for creating a new contact group:
+ *
+ * @code
+ *
+ * using namespace Akonadi;
+ *
+ * ContactGroupEditor *editor = new ContactGroupEditor( Akonadi::ContactGroupEditor::CreateMode, this );
+ *
+ * ...
+ *
+ * if ( !editor->saveContactGroup() ) {
+ *   qDebug() << "Unable to save new contact group to storage";
+ *   return;
+ * }
+ *
+ * @endcode
+ *
+ * Example for editing an existing contact group:
+ *
+ * @code
+ *
+ * const Akonadi::Item contactGroup = ...;
+ *
+ * ContactGroupEditor *editor = new ContactGroupEditor( Akonadi::ContactGroupEditor::EditMode, this );
+ * editor->loadContactGroup( contactGroup );
+ *
+ * ...
+ *
+ * if ( !editor->saveContactGroup() ) {
+ *   qDebug() << "Unable to save changed contact group to storage";
+ *   return;
+ * }
+ *
+ * @endcode
  *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4

akonadi/contact/contactgroupeditordialog.h

@@ -34,7 +34,41 @@ class Item;
 class ContactGroupEditor;
 
 /**
- * @short A dialog for editing a contact group.
+ * @short A dialog for creating or editing a contact group in Akonadi.
+ *
+ * This dialog provides a way to create a new contact group or edit
+ * an existing contact group in Akonadi.
+ *
+ * Example for creating a new contact group:
+ *
+ * @code
+ *
+ * Akonadi::ContactGroupEditorDialog dlg( Akonadi::ContactGroupEditorDialog::CreateMode, this );
+ *
+ * if ( dlg.exec() ) {
+ *   qDebug() << "New contact group has been added to the address book";
+ * } else {
+ *   qDebug() << "User has canceled operation";
+ * }
+ *
+ * @endcode
+ *
+ * Example for editing an existing contact group:
+ *
+ * @code
+ *
+ * const Akonadi::Item contactGroup = ...;
+ *
+ * Akonadi::ContactGroupEditorDialog dlg( Akonadi::ContactGroupEditorDialog::EditMode, this );
+ * dlg.setContactGroup( contactGroup );
+ *
+ * if ( dlg.exec() ) {
+ *   qDebug() << "Contact group has been edited";
+ * } else {
+ *   qDebug() << "User has canceled operation";
+ * }
+ *
+ * @endcode
  *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4

akonadi/contact/contactgroupviewer.h

@@ -33,6 +33,22 @@ namespace Akonadi {
 /**
  * @short A viewer component for contact groups in Akonadi.
  *
+ * This widgets provides a way to show a contact group from the
+ * Akonadi storage.
+ *
+ * Example:
+ *
+ * @code
+ *
+ * using namespace Akonadi;
+ *
+ * const Item group = ...
+ *
+ * ContactGroupViewer *viewer = new ContactGroupViewer( this );
+ * viewer->setContactGroup( group );
+ *
+ * @endcode
+ *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4
  */

akonadi/contact/contactgroupviewerdialog.h

@@ -33,6 +33,21 @@ class Item;
 /**
  * @short A dialog for displaying a contact group in Akonadi.
  *
+ * This dialog provides a way to show a contact group from the
+ * Akonadi storage.
+ *
+ * Example:
+ *
+ * @code
+ *
+ * const Akonadi::Item group = ...
+ *
+ * Akonadi::ContactGroupViewerDialog dlg( this );
+ * dlg.setContactGroup( group );
+ * dlg.exec();
+ *
+ * @endcode
+ *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4
  */

akonadi/contact/contactviewer.h

@@ -33,6 +33,22 @@ namespace Akonadi {
 /**
  * @short A viewer component for contacts in Akonadi.
  *
+ * This widgets provides a way to show a contact from the
+ * Akonadi storage.
+ *
+ * Example:
+ *
+ * @code
+ *
+ * using namespace Akonadi;
+ *
+ * const Item contact = ...
+ *
+ * ContactViewer *viewer = new ContactViewer( this );
+ * viewer->setContact( contact );
+ *
+ * @endcode
+ *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4
  */

akonadi/contact/contactviewerdialog.h

@@ -33,6 +33,21 @@ class Item;
 /**
  * @short A dialog for displaying a contact in Akonadi.
  *
+ * This dialog provides a way to show a contact from the
+ * Akonadi storage.
+ *
+ * Example:
+ *
+ * @code
+ *
+ * const Akonadi::Item contact = ...
+ *
+ * Akonadi::ContactViewerDialog dlg( this );
+ * dlg.setContact( contact );
+ * dlg.exec();
+ *
+ * @endcode
+ *
  * @author Tobias Koenig <tokoe@kde.org>
  * @since 4.4
  */