Update Neptune UI API documentation according to Qt Style

Neptune UI API documentation updates:
* \qmlmodule pages created for Neptune UI components and Interfaces
* part of internal API: PopupInterface::updatePopup() and
NavigationUIScreen::widgetSurface()
* minor grammar fixes

Task-number: QTAUTO-532
Change-Id: I4e0e01b2a6e5818fefb9714cfd8123ea7742b662
Reviewed-by: Nedim Hadzic <nedim.hadzic@pelagicore.com>

8 files changed, 118 insertions, 63 deletions

diff --git a/doc/neptuneui-project.qdocconf b/doc/neptuneui-project.qdocconf
index b69134b..1e679e3 100644
--- a/doc/neptuneui-project.qdocconf
+++ b/doc/neptuneui-project.qdocconf
@@ -18,12 +18,23 @@ qhp.NeptuneUI.filterAttributes = NeptuneUI $QT_VERSION
 qhp.NeptuneUI.customFilters.NeptuneUI.name = Neptune UI $QT_VERSION
 qhp.NeptuneUI.customFilters.NeptuneUI.filterAttributes = NeptuneUI $QT_VERSION
 
-qhp.NeptuneUI.subprojects                   = manual
+qhp.NeptuneUI.subprojects                   = manual components interfaces
 qhp.NeptuneUI.subprojects.manual.title      = Neptune UI
 qhp.NeptuneUI.subprojects.manual.indexTitle = Neptune UI TOC
 qhp.NeptuneUI.subprojects.manual.selectors  = manual
 
+qhp.NeptuneUI.subprojects.components.title  = Neptune UI Components
+qhp.NeptuneUI.subprojects.components.indexTitle = Neptune UI Components
+qhp.NeptuneUI.subprojects.components.selectors  = qmlmodule:utils
+qhp.NeptuneUI.subprojects.components.sortPages  = true
+
+qhp.NeptuneUI.subprojects.interfaces.title  = Neptune UI Interfaces
+qhp.NeptuneUI.subprojects.interfaces.indexTitle = Neptune UI Interfaces
+qhp.NeptuneUI.subprojects.interfaces.selectors  = qmlmodule:service
+qhp.NeptuneUI.subprojects.interfaces.sortPages  = true
+
 navigation.landingpage = "Neptune UI"
 navigation.homepage    = "Qt Automotive Suite"
+navigation.qmltypespage = "Neptune UI Components and Interfaces"
 
 macro.QAS = "Qt Automotive Suite"
diff --git a/doc/src/neptuneui-index.qdoc b/doc/src/neptuneui-index.qdoc
index efd88a5..884c3df 100644
--- a/doc/src/neptuneui-index.qdoc
+++ b/doc/src/neptuneui-index.qdoc
@@ -198,16 +198,17 @@
    \l{Neptune UI Application Development} provides a set of best practices
    for developing applications with Neptune UI.
 
-   See \l{Neptune UI Components} for a list of all provided UI components.
+   See \l{Neptune UI Components and Interfaces} for a list of all
+   provided UI components and interfaces.
 */
 
 /*!
    \page neptuneui-components.html
-   \title Neptune UI Components
+   \title Neptune UI Components and Interfaces
    \previouspage neptune-app-development.html
    \nextpage neptuneui-index.html
 
-   Neptune UI components:
+   Neptune UI components and interfaces:
    \list
        \li \l{UIScreen}
        \li \l{AppUIScreen}
@@ -216,3 +217,32 @@
        \li \l{PopupInterface}
    \endlist
 */
+
+/*!
+    \qmlmodule utils 1.0
+    \title Neptune UI Components
+    \brief List of Neptune UI Components.
+
+    To import Neptune UI components, add the following import statement to your .qml file:
+
+    \qml
+    import utils 1.0
+    \endqml
+
+    Neptune UI provides the following components:
+*/
+
+/*!
+    \qmlmodule service 1.0
+    \title Neptune UI Interfaces
+    \brief List of Neptune UI Interfaces.
+
+    To import Neptune UI interfaces, add the following import statement to your .qml file:
+
+    \qml
+    import service 1.0
+    \endqml
+
+    Neptune UI provides the following interfaces:
+*/
+
diff --git a/doc/src/neptuneui-toc.qdoc b/doc/src/neptuneui-toc.qdoc
index 7890eeb..12aae14 100644
--- a/doc/src/neptuneui-toc.qdoc
+++ b/doc/src/neptuneui-toc.qdoc
@@ -45,7 +45,7 @@
         \list
             \li \l{Building and Running Neptune UI}
             \li \l{Neptune UI Application Development}
-            \li \l{Neptune UI Components}
+            \li \l{Neptune UI Components and Interfaces}
             \list
                 \li \l{UIScreen}
                 \li \l{AppUIScreen}
diff --git a/imports/shared/service/notification/NotificationInterface.qml b/imports/shared/service/notification/NotificationInterface.qml
index 82ea606..b6ad2f2 100644
--- a/imports/shared/service/notification/NotificationInterface.qml
+++ b/imports/shared/service/notification/NotificationInterface.qml
@@ -36,15 +36,18 @@ import QtApplicationManager 1.0
     \qmltype NotificationInterface
     \inqmlmodule service
     \inherits Notification
-    \brief NotificationInterface provides an interface for requesting notifications.
+    \brief An interface for requesting notifications.
 
-    NotificationInterface inherits \l {https://doc.qt.io/QtApplicationManager/qml-qtapplicationmanager-notification.html}
-    {Notification} component and acts like an adapter for Neptune UI. Some properties are adopted
-    to match Neptune UI requirements. Properties \c timeout and \c category are modified and adopted for Neptune UI and
-    should not be used. By Neptune interaction design, notification should be dissmissed by user and
-    not by the timeout.
+    NotificationInterface inherits \l {Notification} from \l{Qt Application Manager}
+    and acts like an adapter for Neptune UI.
+    The NotificationInterface properties \c timeout and \c category are adopted
+    to match Neptune UI requirements and should not be used. In the Neptune UI
+    interaction, notifications should always be dismissed by an end user
+    instead of a time-out.
 
-    Example usage:
+    \section2 Example Usage
+
+    The following example demonstrates the NotificationInterface usage:
 
     \qml
 
@@ -56,10 +59,9 @@ import QtApplicationManager 1.0
     }
     \endqml
 
-    As shown in example \c summary property will act like a title of the notification, while
-    \c body as notification description. Based on the \c priority notification will be queued.
-    It is important to set an absolute path for the \c icon property. Otherwise, an icon will
-    not be shown.
+    \c summary defines a notification title. \c body defines a notification
+    description. Notifications are queued based on a value in \c priority.
+    \c icon must contain an absolute icon path. Otherwise, the icon is not shown.
 */
 
 Notification {
diff --git a/imports/shared/service/popup/PopupInterface.qml b/imports/shared/service/popup/PopupInterface.qml
index 6ecb0e2..219063f 100644
--- a/imports/shared/service/popup/PopupInterface.qml
+++ b/imports/shared/service/popup/PopupInterface.qml
@@ -36,15 +36,16 @@ import QtApplicationManager 1.0
     \qmltype PopupInterface
     \inqmlmodule service
     \inherits Notification
-    \brief PopupInterface provides an interface for requesting popups.
+    \brief An interface for requesting popups.
 
-    PopupInterface inherits \l {https://doc.qt.io/QtApplicationManager/qml-qtapplicationmanager-notification.html}
-    {Notification} component and acts like an adapter for Neptune UI popups. Some properties are adopted
-    to match Neptune UI popup requirements. Properties \c timeout and \c category are modified and adopted for Neptune UI and
-    should not be used. By Neptune interaction design, popups should be dissmissed by user and
-    not by the timeout.
+    PopupInterface inherits \l{Notification} from \l{Qt Application Manager} and
+    acts like an adapter for Neptune UI popups.
+    The PopupInterface properties \c timeout and \c category are adopted
+    to match Neptune UI requirements and should not be used. In the Neptune UI
+    interaction, pop-ups should always be dismissed by an end user
+    instead of a time-out.
 
-    Example usage:
+    \section2 Example Usage
 
     \qml
 
@@ -58,8 +59,8 @@ import QtApplicationManager 1.0
 
     \endqml
 
-    Based on the \c priority popups will be queued. The \c actions property defines an array
-    of buttons for popup.
+    Pop-up notifications are queued based on a value in \c priority. \c actions
+    defines an array of buttons for a popup.
 */
 
 Notification {
@@ -71,7 +72,7 @@ Notification {
     /*!
          \qmlproperty string AppUIScreen::title
 
-         This property assigns title of the popup.
+         This property assigns a title for the popup.
     */
 
     property string title: ""
@@ -79,7 +80,7 @@ Notification {
     /*!
          \qmlproperty string AppUIScreen::subtitle
 
-         This property assigns subtitle of the popup.
+         This property assigns a subtitle for the popup.
     */
 
     property string subtitle: ""
@@ -92,6 +93,9 @@ Notification {
         root.updatePopup();
     }
 
+    /*!
+        \internal
+    */
     function updatePopup() {
         root.extended = {
             "title": root.title,
diff --git a/imports/shared/utils/AppUIScreen.qml b/imports/shared/utils/AppUIScreen.qml
index e58c069..f31791e 100644
--- a/imports/shared/utils/AppUIScreen.qml
+++ b/imports/shared/utils/AppUIScreen.qml
@@ -39,16 +39,17 @@ import utils 1.0
     \qmltype AppUIScreen
     \inqmlmodule utils
     \inherits ApplicationManagerWindow
-    \brief AppUIScreen provides base item for developing the applications.
+    \brief A base QML item for developing applications.
 
-    AppUIScreen is a QML item which should be a root element for every
-    Neptune application. It provides APIs to interact with the system UI and
-    to position application visual elements.
+    AppUIScreen is a QML item which should be a root element in every
+    Neptune UI application. It provides APIs for interacting with a system UI and
+    for positioning the application's visual elements.
 
-    Check { Neptune Application Development }  { Neptune Application Development }
-    for best practices on how to use the APIs.
+    See \l{Neptune UI Application Development} for best practices on how to use the APIs.
 
-    Example usage:
+    \section2 Example Usage
+
+    The following example uses \l{AppUIScreen} as a root element:
 
     \qml
 
@@ -78,7 +79,7 @@ ApplicationManagerWindow {
     /*!
          \qmlproperty Item AppUIScreen::content
 
-         This default property specifies the content area for application visual content.
+         A default property that specifies a content area for the application's visual content.
     */
 
     default property alias content: content.children
@@ -86,18 +87,24 @@ ApplicationManagerWindow {
     /*!
          \qmlproperty Item AppUIScreen::cluster
 
-         This property assigns visual content for the cluster window, if cluster
-         is available.
+         If a cluster is available, this property assigns visual content for the cluster window.
     */
 
     property alias cluster: clusterContainer.children
 
+    /*!
+         \qmlsignal AppUIScreen::clusterKeyPressed(int key)
+
+         This signal is emitted every time a key is pressed in a cluster.
+
+    */
+
     signal clusterKeyPressed(int key)
 
     /*!
          \qmlsignal AppUIScreen::raiseApp()
 
-         The signal which is emitted every time application starts.
+         This signal is emitted every time an application is started.
 
     */
 
@@ -106,7 +113,8 @@ ApplicationManagerWindow {
     /*!
          \qmlsignal AppUIScreen::closeApp()
 
-         The signal is emitted every time application closes (back button clicked).
+         This signal is emitted every time an application is closed by clicking
+         the back button.
 
     */
 
@@ -115,10 +123,8 @@ ApplicationManagerWindow {
     /*!
         \qmlmethod AppUIScreen::back()
 
-        This method is called when an application needs to exit.
-
-        When user clicks on back button of the application, this method
-        makes sure system UI screen is shown.
+        This method is called when an application needs to exit. It ensures the
+        system UI screen visibility when a back button is clicked.
 
         \qml
         AppUIScreen {
@@ -137,7 +143,6 @@ ApplicationManagerWindow {
         }
         \endqml
 
-        \sa fullScreenContent
     */
 
 
diff --git a/imports/shared/utils/NavigationUIScreen.qml b/imports/shared/utils/NavigationUIScreen.qml
index 13de612..eabf920 100644
--- a/imports/shared/utils/NavigationUIScreen.qml
+++ b/imports/shared/utils/NavigationUIScreen.qml
@@ -39,18 +39,17 @@ import utils 1.0
     \qmltype NavigationUIScreen
     \inqmlmodule utils 1.0
     \inherits AppUIScreen
-    \brief NavigationUIScreen provides base item for developing
-    navigation applciations.
+    \brief A base item for developing navigation applications.
 
-    NavigationUIScreen is a QML item which should be a root element for navigation
-    Neptune application. It provides APIs to interact with the system UI and
-    to position application visual elements. Main difference from \l AppUIScreen
-    is additional properties, which provide option to set the home page map widget.
+    NavigationUIScreen is a QML item which should be the root element in
+    Neptune UI navigation applications. It provides APIs for interacting with a system UI and
+    for positioning the application's visual elements. NavigationUIScreen extends
+    \l AppUIScreen with additional properties for setting a home page map widget.
 
-    Check { Neptune Application Development }  { Neptune Application Development }
-    for best practices on how to use the APIs.
+    See \l{Neptune UI Application Development} for best practices on how to use the APIs.
+
+    \section2 Example Usage
 
-    Example usage:
     \qml
 
     NavigationUIScreen {
@@ -82,12 +81,15 @@ AppUIScreen {
     /*!
          \qmlproperty Item AppUIScreen::widget
 
-         This property specifies the content area for map widget, which
-         will be placed on the home page of the system UI.
+         This property specifies a content area for a map widget. The content
+         area will be placed in a system UI home page.
     */
 
     property alias widget: widgetContainer.children
 
+    /*!
+        \internal
+    */
     property var widgetSurface: ApplicationManagerWindow {
         width: Style.hspan(12)
         height: Style.vspan(19)
diff --git a/imports/shared/utils/UIScreen.qml b/imports/shared/utils/UIScreen.qml
index 2e9dde6..d8dbd6f 100644
--- a/imports/shared/utils/UIScreen.qml
+++ b/imports/shared/utils/UIScreen.qml
@@ -38,13 +38,13 @@ import controls 1.0
     \qmltype UIScreen
     \inqmlmodule utils
     \inherits Page
-    \brief UIScreen provides base item for Neptune screens.
+    \brief A base item for all Neptune UI screens.
 
-    UIScreen is a QML item used to provide Neptune application screens. UIScreen
-    provides correct layout with back buttons, which provides getting to the previous
+    UIScreen is a QML item that provides Neptune UI application screens. UIScreen
+    has a layout with back buttons that provides access to a previous
     screen.
 
-    Example usage:
+    \section2 Example Usage
 
     \qml
 
@@ -64,7 +64,7 @@ import controls 1.0
     }
     \endqml
 
-    For each screen an application has, UIScreen should be used as a base.
+    For each screen an application has, UIScreen should be used as a base item.
 
 */
 
@@ -78,8 +78,9 @@ Page {
     /*!
          \qmlproperty bool UIScreen::hideBack
 
-         Defines if back button of the screen should be hidden. Default
-         value is false.
+         This property holds the visibility status of a back button.
+         If hideBack is set to \c true, the back button is hidden. Default
+         value is \c false.
     */
 
     property bool hideBack: false
@@ -87,7 +88,7 @@ Page {
     /*!
          \qmlsignal UIScreen::backScreen()
 
-         The signal is emitted when user clicks on back button.
+         The signal is emitted when a back button is selected.
 
     */