--- a/src/hbwidgets/devicedialogs/hbdevicemessageboxsymbian.cpp	Tue Jul 06 14:36:53 2010 +0300
+++ b/src/hbwidgets/devicedialogs/hbdevicemessageboxsymbian.cpp	Wed Aug 18 10:05:37 2010 +0300
@@ -385,7 +385,7 @@
             if (i == EAcceptText || i == ERejectText) {
                 HBufC *actionData = CreateActionDataLC(property.IsNullAction(), property.StringValue());
                 parameter = CHbSymbianVariant::NewL(actionData, CHbSymbianVariant::EDes);
-                CleanupStack::PopAndDestroy(); // actionData
+                CleanupStack::PopAndDestroy(actionData);
             } else if (property.Type() == TMessageBoxProperty::EIntProperty) {
                 TInt value = property.IntValue();
                 parameter = CHbSymbianVariant::NewL(&value, CHbSymbianVariant::EInt);
@@ -396,7 +396,7 @@
             CleanupStack::PushL(parameter);
             User::LeaveIfError(parameters->Add(
                 PropertyName(static_cast<TPropertyId>(i)), parameter));
-            CleanupStack::Pop(); // parameter
+            CleanupStack::Pop(parameter);
             property.SetModified(false);
         }
     }
@@ -416,7 +416,7 @@
             User::Leave(error); // error can be positive or negative
         }
     }
-    CleanupStack::PopAndDestroy(); // parameters
+    CleanupStack::PopAndDestroy(parameters);
 }
 
 // Close message box
@@ -551,7 +551,7 @@
     It provides a similar interface as HbDeviceMessageBox. The main
     differences are:
     - Signals are replaced by an observer interface
-    - HbAction/QAction is replaced by button information.
+    - HbAction/QAction is replaced by button text.
     - Function parameters whose type is a Qt or Hb enumeration are replaced by an integer.
       As suitable default values are set at construction, it is assumed that application rarely
       needs to use these.
@@ -559,11 +559,17 @@
     Device message box is a modal dialog. It is shown on top of applications by device dialog
     server. CHbDeviceMessageBoxSymbian is a client of the server.
 
-    Three predefined message boxes are provided or a custom one can be constructed using the API.
-    Predefined message boxes are:
-    - Information
-    - Question
-    - Warning
+    Four types of message boxes are predefined. The type determines a set of default properties that
+    are set on construction. Below is a table listing types and their default properties.
+
+    <table border="1">
+        <caption><b>HbDeviceMessageBox types and default properties</b></caption>
+        <tr><th>Type</th><th>Icon</th><th>Buttons</th><th>Timeout</th><th>Dismiss policy</th><th>Sound</th></tr>
+        <tr><td>ENone</td><td>No icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>No sound</td></tr>
+        <tr><td>EInformation</td><td>Info icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>Info sound</td></tr>
+        <tr><td>EWarning</td><td>Warning icon</td><td>"Ok" button</td><td>Standard timeout</td><td>Tap anywhere</td><td>Warn sound</td></tr>
+        <tr><td>EQuestion</td><td>Question icon</td><td>"Yes" and "No" buttons</td><td>No timeout</td><td>Button press</td><td>Question sound</td></tr>
+    </table>
 
     ShowL() displays a message box asynchronously. The function returns immediately. The launched
     dialog can be updated by setters and then calling UpdateL(). Closing can be observed by a
@@ -585,7 +591,7 @@
     static functions contain a default set of properties depending on the message box type and their
     contents cannot be updated while the message box executes.
 
-    Supported animation formats are following:
+    Supported icon animation formats are following:
     - GIF (.gif)
     - MNG (.mng)
         - Frame animations
@@ -673,11 +679,11 @@
 
 /*!
     \enum CHbDeviceMessageBoxSymbian::TType
-    Predefined device message boxes.
+    Message box type. Determines a set of default properties for the message box.
 */
 /*!
     \var CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::ENone
-    Message box with no icon and audio defined by default.
+    Message box with no icon and audio defined.
 */
 /*!
     \var CHbDeviceMessageBoxSymbian::TType CHbDeviceMessageBoxSymbian::EInformation
@@ -743,7 +749,7 @@
 /*!
     Factory function. Returns pointer to a device message box.
 
-    \param aType Selects a template for the message box. Information, question or warning.
+    \param aType Selects a template for the message box. None, information, question or warning.
     \param aObserver Observer for message box close event
 */
 EXPORT_C CHbDeviceMessageBoxSymbian* CHbDeviceMessageBoxSymbian::NewL(TType aType,
@@ -757,7 +763,7 @@
     CleanupStack::PushL(mboxPrivate);
     mboxPrivate->ConstructL(aType, aObserver);
     messageBox->d = mboxPrivate;
-    CleanupStack::Pop(2); // messageBox, mboxPrivate
+    CleanupStack::Pop(2, messageBox); // mboxPrivate, messageBox
     messageBox->SetObserver(aObserver);
     return messageBox;
 }
@@ -765,7 +771,7 @@
 /*!
     Static convenience function to create and show a question device message box. Waits for
     the message box to close and returns button selected. If message box was closed for other
-    reason than button press, returns EInvalidButton.
+    reason than button press, returns CHbDeviceMessageBoxSymbian::EInvalidButton.
 
     <b> Beware that Symbian event processing is running while the function executes. For example
     application may have exited when the function returns.</b>
@@ -788,14 +794,14 @@
         messageBox->SetButtonTextL(ERejectButton, aRejectButtonText);
     }
     TButtonId buttonId = messageBox->ExecL();
-    CleanupStack::PopAndDestroy(); // messageBox
+    CleanupStack::PopAndDestroy(messageBox);
     return buttonId;
 }
 
 /*!
     Static convenience function to create and show a question device message box. Waits for
     the message box to close and returns button selected. If message box was closed for other
-    reason than button press, returns EInvalidButton.
+    reason than button press, returns CHbDeviceMessageBoxSymbian::EInvalidButton.
 
     <b> Beware that Symbian event processing is running while the function executes. For example
     application may have exited when the function returns.</b>
@@ -815,12 +821,13 @@
     }
     messageBox->SetStandardButtons(aStandardButtons);
     TButtonId buttonId = messageBox->ExecL();
-    CleanupStack::PopAndDestroy(); // messageBox
+    CleanupStack::PopAndDestroy(messageBox);
     return buttonId;
 }
 
 /*!
-    Static convenience function to create and show an information device message box.
+    Static convenience function to create and show an information device message box. Returns
+    immediately (doesn't wait for the box to close).
 
     \param aText Message box text.
 */
@@ -830,11 +837,12 @@
     CleanupStack::PushL(messageBox);
     messageBox->SetTextL(aText);
     messageBox->ShowL();
-    CleanupStack::PopAndDestroy(); // messageBox
+    CleanupStack::PopAndDestroy(messageBox);
 }
 
 /*!
-    Static convenience function to create and show a warning device message box.
+    Static convenience function to create and show a warning device message box. Returns
+    immediately (doesn't wait for the box to close).
 
     \param aText Message box text.
 */
@@ -844,7 +852,7 @@
     CleanupStack::PushL(messageBox);
     messageBox->SetTextL(aText);
     messageBox->ShowL();
-    CleanupStack::PopAndDestroy(); // messageBox
+    CleanupStack::PopAndDestroy(messageBox);
 }
 
 /*!
@@ -873,9 +881,10 @@
 }
 
 /*!
-    Closes a device message box.
+    Closes a device message box. Closing of the message box can be observer with
+    MHbDeviceMessageBoxObserver.
 
-    \sa ShowL()
+    \sa ShowL(),  SetObserver()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::Close()
 {
@@ -885,7 +894,7 @@
 /*!
     Shows a device message box synchronously. Function launches the message box and waits for it
     to close. Returns a button that was selected. If message box was closed for other reason
-    than button press, returns EInvalidButton.
+    than button press, returns CHbDeviceMessageBoxSymbian::EInvalidButton.
 
     <b> Beware that Symbian event processing is running while the function executes. For example
     application may have exited when the function returns.</b>
@@ -906,11 +915,12 @@
 
 /*!
     Sets message box type. All message box properties are reset to a default values for the type.
-    A ShowL() must be called to launch a message box after SetTypeL() has been called.
+    Type of a showing message box cannot be changed on the fly. A ShowL() must be called to launch
+    a new message box after SetTypeL() has been called.
 
     \param aType Message box type.
 
-    \sa Type()
+    \sa Type(), ShowL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTypeL(TType aType)
 {
@@ -930,12 +940,11 @@
 }
 
 /*!
-    Sets message box text. The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box text.
 
     \param aText Message box text.
 
-    \sa Text()
+    \sa Text(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTextL(const TDesC& aText)
 {
@@ -953,13 +962,12 @@
 }
 
 /*!
-    Sets message box icon name or animation logical name. The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box icon name or animation logical name.
 
     \param aIconName Icon name. Icon can be from Hb resources or themes. Or can be a file in
     a file system.
 
-    \sa IconName()
+    \sa IconName(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconNameL(const TDesC& aIconName)
 {
@@ -977,19 +985,18 @@
 }
 
 /*!
-    Sets message box animation definition name.  The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box animation definition name.
 
-    Supported animation formats are following:
+    Supported icon animation formats are following:
     - GIF (.gif)
     - MNG (.mng)
-        - Frame animations
+    - Frame animations
 
     \param aAnimationDefinition Animation definition file name. Definition can be from Hb resources or themes.
     Or can be a file in a file system. The definition must be stored to a place where it can be accessed by
     device dialog service.
 
-    \sa AnimationDefinition() SetIconNameL() HbIconAnimationManager::addDefinitionFile()
+    \sa AnimationDefinition() SetIconNameL() HbIconAnimationManager::addDefinitionFile(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetAnimationDefinitionL(const TDesC& aAnimationDefinition)
 {
@@ -1007,12 +1014,11 @@
 }
 
 /*!
-    Sets message box icon visibility. The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box icon visibility.
 
     \param aVisible Icon visibility.
 
-    \sa IconVisible()
+    \sa IconVisible(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetIconVisible(TBool aVisible)
 {
@@ -1020,7 +1026,8 @@
 }
 
 /*!
-    Returns message box icon visibility.
+    Returns message box icon visibility. Default value is true for message box
+    types other than ENone.
 
     \sa SetIconVisible()
 */
@@ -1030,12 +1037,11 @@
 }
 
 /*!
-    Sets message box timeout. The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box timeout.
 
     \param aTimeout Timeout in milliseconds. Zero denotes no timeout.
 
-    \sa Timeout()
+    \sa Timeout(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetTimeout(TInt aTimeout)
 {
@@ -1043,7 +1049,9 @@
 }
 
 /*!
-    Returns message box timeout value in milliseconds.
+    Returns message box timeout value in milliseconds. Default value depends on message box type.
+    Question message box has a default of HbPopup::NoTimeout. All other boxes, the default is
+    HbPopup::StandardTimeout.
 
     \sa SetTimeout()
 */
@@ -1053,12 +1061,11 @@
 }
 
 /*!
-    Sets message box dismiss policy. The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box dismiss policy.
 
     \param aHbPopupDismissPolicy Dismiss policy. Values are HbPopup::DismissPolicy flags.
 
-    \sa HbPopup::DismissPolicy, DismissPolicy()
+    \sa HbPopup::DismissPolicy, DismissPolicy(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetDismissPolicy(TInt aHbPopupDismissPolicy)
 {
@@ -1068,6 +1075,8 @@
 
 /*!
     Returns message box dismiss policy. Returned values are HbPopup::DismissPolicy flags.
+    Default depends on message box type. Question box has default HbPopup::NoDismiss and
+    all other boxes HbPopup::TapAnywhere.
 
     \sa HbPopup::DismissPolicy, SetDismissPolicy()
 */
@@ -1077,13 +1086,12 @@
 }
 
 /*!
-    Sets message box button text. The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box button text.
 
     \param aButton Selects the button.
     \param aText Button text.
 
-    \sa ButtonText()
+    \sa ButtonText(), SetButton(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetButtonTextL(TButtonId aButton, const TDesC& aText)
 {
@@ -1091,7 +1099,8 @@
 }
 
 /*!
-    Returns message box button text.
+    Returns message box button text. Question message box by default has "Yes" and "No" buttons.
+    Other message boxes have a single "Ok" button.
 
     \param aButton Selects the button.
 
@@ -1106,13 +1115,12 @@
 }
 
 /*!
-    Sets message box button presence. The message box gets updated next time ShowL() or UpdateL()
-    is called.
+    Sets message box button presence.
 
     \param aButton Selects the button.
     \param aEnable True enables (makes visible) message box button.
 
-    \sa HasButton()
+    \sa HasButton(), SetButtonTextL(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetButton(TButtonId aButton, TBool aEnable)
 {
@@ -1120,11 +1128,12 @@
 }
 
 /*!
-    Returns message box button presence.
+    Returns message box button presence. Question message box by default has accept and reject
+    buttons. Other message boxes have a single accept button.
 
     \param aButton Selects the button.
 
-    \sa SetButton()
+    \sa SetButton(), ButtonText()
 */
 EXPORT_C TBool CHbDeviceMessageBoxSymbian::HasButton(TButtonId aButton) const
 {
@@ -1137,11 +1146,12 @@
 /*!
     Sets message box buttons to standard buttons.
 
-    \param aButtons Message box buttons. A combination of flags,
-    eg. HbMessageBox::Yes | HbMessageBox::No. Button flags are scanned starting from lsb.
-    First button found goes to accept position and so forth.
+    \param aButtons Message box buttons. A combination of flags, eg.
+    HbMessageBox::Yes | HbMessageBox::No.
+    Button flags are scanned starting from lsb. First button found goes to accept position
+    and so forth.
 
-    \sa StandardButtons()
+    \sa HbMessageBox::StandardButton, StandardButtons(), ShowL(), UpdateL()
 */
 EXPORT_C void CHbDeviceMessageBoxSymbian::SetStandardButtons(TUint aButtons)
 {
@@ -1150,10 +1160,10 @@
 
 /*!
     Returns standard buttons set to a message box. A default value for question message box is
-    HbMessageBox::Yes|HbMessageBox::No. For all other message box types the default is
+    HbMessageBox::Yes | HbMessageBox::No. For all other message box types the default is
     HbMessageBox::Ok.
 
-    \sa SetStandardButtons()
+    \sa HbMessageBox::StandardButton, SetStandardButtons()
 */
 EXPORT_C TUint CHbDeviceMessageBoxSymbian::StandardButtons() const
 {