doc: Clean up the qml api docs

Fix weird language, remove non-existent stuff, take the updated descriptions
from the C++ APIs in a few cases, and add a few enhancements, in particular for
DataInput and SubPresentationSettings.

Change-Id: Icea43b5975bc05625c984f0cef8a2d1aa2f94ae6
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

8 files changed, 335 insertions, 170 deletions

diff --git a/src/imports/studio3d/q3dsstudio3ditem.cpp b/src/imports/studio3d/q3dsstudio3ditem.cpp
index b585122..1c16b89 100644
--- a/src/imports/studio3d/q3dsstudio3ditem.cpp
+++ b/src/imports/studio3d/q3dsstudio3ditem.cpp
@@ -89,36 +89,42 @@ QT_BEGIN_NAMESPACE
         }
     }
     \endqml
-*/
 
-/*!
-    \qmlsignal Studio3D::frameUpdate()
+    \section2 Controlling the presentation
 
-    This signal is emitted each time a frame has been updated regardless of
-    visibility. This allows a hidden Studio3D element to still process
-    information every frame, even though the renderer is not rendering.
+    Like the example above suggests, Studio3D and the other types under the
+    QtStudio3D import offer more than simply rendering the animated Qt 3D
+    Studio presentation. They also offer scene manipulation, including
 
-    The corresponding handler is \c onFrameUpdate.
+    \list
 
-    To prevent expensive handlers from being processed when hidden, add an
-    early return to the top like:
+    \li querying and changing scene object properties (for example, the
+    transform of a model, colors and other settings of a material, etc.) via
+    Presentation::getAttribute(), Presentation::setAttribute(), \l Element, and
+    \l DataInput,
 
-    \qml
-         onFrameUpdate: {
-             if (!visible) return;
-             ...
-         }
-    \endqml
+    \li changing slides (and thus starting the relevant animations and applying
+    the scene object property changes associated with the new slide) via
+    Presentation::goToSlide(), \l SceneElement, and \l DataInput,
+
+    \li and controlling the timeline (the current playback position for the
+    key-frame based animations) both on the main scene and on individual
+    Component nodes via Presentation::goToTime(), \l SceneElement, and \l DataInput.
+
+    \endlist
+*/
+
+/*!
+    \qmlsignal Studio3D::frameUpdate()
+
+    This signal is emitted each time a frame has been rendered.
 */
 
 /*!
     \qmlsignal Studio3D::presentationReady()
 
     This signal is emitted when the viewer has been initialized and the
-    presentation is ready to be shown. The difference to \c running property is
-    that the viewer has to be visible for \c running to get \c{true}. This
-    signal is useful for displaying splash screen while viewer is getting
-    initialized.
+    presentation is ready to be shown.
 */
 
 static bool engineCleanerRegistered = false;
@@ -181,6 +187,16 @@ bool Q3DSStudio3DItem::isRunning() const
     return m_running;
 }
 
+/*!
+    \qmlproperty string Studio3D::error
+
+    Contains the text for the error message that was generated during the
+    loading of the presentation. When no error occurred or there is no
+    presentation loaded, the value is an empty string.
+
+    This property is read-only.
+*/
+
 QString Q3DSStudio3DItem::error() const
 {
     return m_error;
diff --git a/src/imports/studio3d/q3dssubpresentationsettings.cpp b/src/imports/studio3d/q3dssubpresentationsettings.cpp
index e8ffcea..44d9e43 100644
--- a/src/imports/studio3d/q3dssubpresentationsettings.cpp
+++ b/src/imports/studio3d/q3dssubpresentationsettings.cpp
@@ -83,6 +83,27 @@ QQmlListProperty<Q3DSInlineQmlSubPresentation> Q3DSSubPresentationSettings::qmlS
         }
     }
     \endqml
+
+    \section2 Linking to the Presentation via presentationId
+
+    In Qt 3D Studio presentations QML sub-presentations are specified in the \e
+    assets element of the presentation's \c{.uia} file. This is important also
+    when using SubPresentationSettings and QmlStream.
+
+    \badcode
+    <assets ...>
+        <presentation-qml id="presentation-id" args="preview-presentation.qml" />
+    </assets>
+    \endcode
+
+    \note the Qt 3D Studio application takes care of generating the \c{.uia}
+    file based on what the designers have set in the Sub-presentations dialog.
+
+    The \c presentation-id attribute must contain a unique ID for the
+    sub-presentation. The corresponding \l QmlStream must provide the same
+    value in its presentationId property. The \c args attribute may contain an
+    optional preview version of the item, which is only used in the Viewer
+    application.
  */
 
 /*!
@@ -97,36 +118,27 @@ QQmlListProperty<Q3DSInlineQmlSubPresentation> Q3DSSubPresentationSettings::qmlS
     \ingroup 3dstudioruntime2
     \brief QML stream.
 
-    This type allows attaching QML sub-presentation with a quick item. The item is rendered to a
-    texture and used as a part of a Qt 3D Studio presentation.
-
-    The sub-presentation element must be specified in the \e assets element of the presentation
-    .uia file:
-
-     \badcode
-     <assets ...>
-         <presentation-qml id="presentation-id" args="preview-presentation.qml" />
-     </assets>
-     \endcode
+    This type allows specifying the contents of a QML sub-presentation within
+    the Studio3D item. QmlStream must be used in combination with
+    \l SubPresentationSettings.
 
-    The \c presentation-id attribute must contain a unique ID of the sub-presentation.
-    The \c args attribute may contain an optional preview version of the item, which is only
-    used in the Viewer application.
+    \sa SubPresentationSettings
  */
 
 /*!
     \qmlproperty string QmlStream::presentationId
 
-    Holds the string ID of the sub-presentation the item is attached to. The id must be one of
-    the \c presentation-qml IDs specified in the .uia file.
+    Holds the string ID of the sub-presentation the contents of which is
+    specified by \l item. The id must be one of the \c presentation-qml IDs
+    specified in the \c{.uia} file.
  */
 
 /*!
     \qmlproperty Item QmlStream::item
 
-    Holds the item attached to the sub-presentation. The item size is used as the the size of the
-    texture the item is rendered to. Default values \c{(256, 256)} are used if the item doesn't
-    specify a size.
+    Holds the item attached to the sub-presentation. The item size is used as
+    the the size of the texture the item is rendered to. A default value of
+    \c{(128, 128)} is used when the item does not specify a size.
  */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dsdatainput.cpp b/src/runtime/api/q3dsdatainput.cpp
index 69cafe3..77b999a 100644
--- a/src/runtime/api/q3dsdatainput.cpp
+++ b/src/runtime/api/q3dsdatainput.cpp
@@ -111,10 +111,11 @@ void Q3DSDataInput::setName(const QString &name)
 
     The value of this property only accounts for changes done via the same
     Q3DSDataInput instance. If the value of the same data input in the
-    presentation is changed elsewhere, for example via presentation scripting,
-    those changes are not reflected in the value of this property. Due to this
-    uncertainty, this property treats all value sets as changes even if the
-    newly set value is the same value as the previous value.
+    presentation is changed elsewhere, for example via animations or
+    Q3DSPresentation::setAttribute(), those changes are not reflected in the
+    value of this property. Due to this uncertainty, this property treats all
+    value sets as changes even if the newly set value is the same value as the
+    previous value.
 */
 QVariant Q3DSDataInput::value() const
 {
@@ -149,9 +150,54 @@ void Q3DSDataInputPrivate::sendValue()
     \instantiates Q3DSDataInput
     \inqmlmodule QtStudio3D
     \ingroup 3dstudioruntime2
-    \brief Control type for data inputs in a Qt 3D Studio presentation.
 
-    This type is a convenience type for controlling a data input in a presentation.
+    \brief Controls a data input entry in a Qt 3D Studio presentation.
+
+    This type is a convenience for controlling a data input in a presentation.
+    Its functionality is equivalent to Presentation::setDataInputValue(),
+    however it has a big advantage of being able to use QML property bindings,
+    thus avoiding the need to having to resort to a JavaScript function call
+    for every value change.
+
+    As an example, compare the following two approaches:
+
+    \qml
+        Studio3D {
+            ...
+            Presentation {
+                id: presentation
+                ...
+            }
+        }
+
+        Button {
+            onClicked: presentation.setAttribute("SomeTextNode", "textstring", "Hello World")
+        }
+    \endqml
+
+    \qml
+        Studio3D {
+            ...
+            Presentation {
+                id: presentation
+                ...
+                property string text: ""
+                DataInput {
+                    name: "inputForSomeTextNode"
+                    value: presentation.text
+                }
+            }
+        }
+
+        Button {
+            onClicked: presentation.text = "Hello World"
+        }
+    \endqml
+
+    The latter assumes that a data input connection was made in Qt 3D Studio
+    between the \c textstring property of \c SomeTextNode and a data input name
+    \c inputForSomeTextNode. As the value is now set via a property, the full
+    set of QML property bindings techniques are available.
 
     \sa Studio3D, Presentation
 */
@@ -159,22 +205,23 @@ void Q3DSDataInputPrivate::sendValue()
 /*!
     \qmlproperty string DataInput::name
 
-    Specifies the name of the controlled data input element in the presentation.
-    This property must be set as part of DataInput declaration.
+    Specifies the name of the controlled data input element in the
+    presentation. This property must be set as part of DataInput declaration,
+    although it is changeable afterwards, if desired.
 */
 
 /*!
     \qmlproperty variant DataInput::value
 
     Specifies the value of the controlled data input element in the presentation.
-    The changes to the value property are queued and handled asynchronously before the
-    next frame is displayed.
-
-    The value of this property only accounts for changes done via the same DataInput instance.
-    If the value of the same data input in the presentation is changed elsewhere,
-    for example via presentation scripting, those changes are not reflected in
-    the value of this property. Due to this uncertainty, this property treats all value sets as
-    changes even if the newly set value is the same value as the previous value.
+
+    The value of this property only accounts for changes done via the same
+    DataInput instance. If the value of the underlying attribute in the
+    presentation is changed elsewhere, for example via animations or
+    Presentation::setAttribute(), those changes are not reflected in the value
+    of this property. Due to this uncertainty, this property treats all value
+    sets as changes even if the newly set value is the same value as the
+    previous value.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dselement.cpp b/src/runtime/api/q3dselement.cpp
index 3e72e83..a09d21e 100644
--- a/src/runtime/api/q3dselement.cpp
+++ b/src/runtime/api/q3dselement.cpp
@@ -37,7 +37,7 @@ QT_BEGIN_NAMESPACE
     \inmodule 3dstudioruntime2
     \since Qt 3D Studio 2.0
 
-    \brief Controls a scene object in a Qt 3D Studio presentation.
+    \brief Controls a scene object (node) in a Qt 3D Studio presentation.
 
     This class is a convenience class for controlling the properties of a scene
     object (such as, model, material, camera, layer) in a Qt 3D Studio
@@ -183,10 +183,12 @@ void Q3DSElementPrivate::setPresentation(Q3DSPresentation *pres)
     \ingroup 3dstudioruntime2
     \brief Control type for elements in a Qt 3D Studio presentation.
 
-    This type is a convenience type for managing a presentation element.
+    This type is a convenience for controlling the properties of a scene object
+    (such as, model, material, camera, layer) in a Qt 3D Studio presentation.
 
-    All methods provided by this type are queued and handled asynchronously before the next
-    frame is displayed.
+    \note The functionality of Element is equivalent to
+    Presentation::setAttribute(), Presentation::getAttribute() and
+    Presentation::fireEvent().
 
     \sa Studio3D, Presentation, SceneElement
 */
@@ -195,37 +197,54 @@ void Q3DSElementPrivate::setPresentation(Q3DSPresentation *pres)
     \qmlproperty string Element::elementPath
 
     Holds the element path of the presentation element.
-    This property must be set as part of Element declaration.
-    You can specify an element of a sub-presentation by adding "SubPresentationId:"
-    in front of the element path, for example \c{"SubPresentationOne:Scene"}.
-*/
 
-/*!
-    \qmlmethod void Element::setAttribute(string attributeName, variant value)
+    An element path refers to an object in the scene either by name or id. The
+    latter is rarely used in application code since the unique IDs are not
+    exposed in the Qt 3D Studio application. To refer to an object by id,
+    prepend \c{#} to the name. Applications will typically refer to objects by
+    name.
 
-    Sets the \a value of an attribute on an element specified by this instance.
-    The \a attributeName is the \l{Attribute Names}{scripting name} of the attribute.
+    Names are not necessarily unique, however. To access an object with a
+    non-unique name, the path can be specified, for example,
+    \c{Scene.Layer.Camera}. Here the right camera object gets chosen even if
+    the scene contains other layers with the default camera names (for instance
+    \c{Scene.Layer2.Camera}).
 
-    The attribute must be preserved for scripting to be set by this function, or else it will fail.
-    An attribute is preserved if it is either \e{animated}, or
-    \e{an attribute on a master element that is unlinked and changed per-slide}.
+    If the object is renamed to a unique name in the Qt 3D Studio application's
+    Timeline view, the path can be omitted. For example, if the camera in
+    question was renamed to \c MyCamera, applications can then simply pass \c
+    MyCamera as the element path.
+
+    To access an object in a sub-presentation, prepend the name of the
+    sub-presentation followed by a colon, for example,
+    \c{SubPresentationOne:Scene.Layer.Camera}.
 */
 
 /*!
-    \qmlmethod void Element::fireEvent(string eventName)
+    \qmlmethod variant Element::getAttribute(string attributeName)
+
+    Returns the current value of an attribute (property) of the scene object
+    specified by this Element instance. The \a attributeName is the
+    \l{Attribute Names}{scripting name} of the attribute.
+ */
 
-    Dispatches an event with \a eventName on the element specified by this instance.
-    Appropriate actions created in Qt 3D Studio or callbacks registered using the registerForEvent()
-    method in attached scripts will be executed in response to the event.
+/*!
+    \qmlmethod void Element::setAttribute(string attributeName, variant value)
+
+    Sets the \a value of an attribute (property) of the scene object specified
+    by this Element instance. The \a attributeName is the \l{Attribute
+    Names}{scripting name} of the attribute.
 */
 
 /*!
-    \qmlsignal Element::elementPathChanged(string elementPath)
+    \qmlmethod void Element::fireEvent(string eventName)
 
-    This signal is emitted when the element path property changes.
-    The new value is provided in the \a elementPath parameter.
+    Dispatches an event with \a eventName on the scene object
+    specified by elementPath.
 
-    The corresponding handler is \c onElementPathChanged.
+    Appropriate actions created in Qt 3D Studio or callbacks registered using
+    the registerForEvent() method in attached \c{behavior scripts} will be
+    executed in response to the event.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dspresentation.cpp b/src/runtime/api/q3dspresentation.cpp
index 0a797b2..9525422 100644
--- a/src/runtime/api/q3dspresentation.cpp
+++ b/src/runtime/api/q3dspresentation.cpp
@@ -476,12 +476,76 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
     \inqmlmodule QtStudio3D
     \ingroup 3dstudioruntime2
 
-    \brief Control type for Qt 3D Studio presentations.
+    \brief Represents a Qt 3D Studio presentation.
+
+    This class provides properties and methods for controlling a
+    presentation.
 
-    This type provides properties and methods for controlling a presentation.
+    Qt 3D Studio supports multiple presentations in one project. There is
+    always a main presentation and zero or more sub-presentations. The
+    sub-presentations are composed into the main presentations either as
+    contents of Qt 3D Studio layers or as texture maps.
+
+    In the filesystem each presentation corresponds to one \c{.uip}
+    file. When present, the \c{.uia} file ties these together by
+    specifying a name for each of the (sub-)presentations and
+    specifies which one is the main one.
 
-    All methods provided by this type are queued and handled asynchronously before the next
-    frame is displayed.
+    From the API point of view Presentation corresponds to the main
+    presentation. The source property can refer either to a \c{.uia} or
+    \c{.uip} file. When specifying a file with \c{.uip} extension and a
+    \c{.uia} is present with the same name, the \c{.uia} is loaded
+    automatically and thus sub-presentation information is available
+    regardless.
+
+    The Presentation type handles child objects of the types \l Element, \l
+    SceneElement, \l DataInput, and \l SubPresentationSettings specially. These
+    will get automatically associated with the presentation and can control
+    certain aspects of it from that point on.
+
+    \section2 Example usage
+
+    \qml
+    Studio3D {
+        Presentation {
+            id: presentation
+
+            source: "qrc:/presentation/barrel.uip"
+            profilingEnabled: true
+
+            onSlideEntered: console.log("Entered slide " + name + "(index " + index + ") on " + elementPath)
+            onSlideExited: console.log("Exited slide " + name + "(index " + index + ") on " + elementPath)
+            onCustomSignalEmitted: console.log("Got custom signal " + name)
+
+            DataInput {
+                name: "di_text"
+                value: "hello world"
+            }
+
+            SceneElement {
+                elementPath: "SomeComponentNode"
+                onCurrentSlideIndexChanged: console.log("Current slide index for component: " + currentSlideIndex)
+                onCurrentSlideNameChanged: console.log("Current slide name for component: " + currentSlideName)
+            }
+
+            SubPresentationSettings {
+                qmlStreams: [
+                    QmlStream {
+                        presentationId: "sub-presentation-id"
+                        Rectangle {
+                            width: 1024
+                            height: 1024
+                            color: "red"
+                        }
+                    }
+                ]
+            }
+        }
+    }
+    Button {
+        onClicked: presentation.setAttribute("SomeMaterial", "diffuse", "0 1 0");
+    }
+    \endqml
 
     \sa Studio3D
 */
@@ -489,22 +553,14 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlproperty url Presentation::source
 
-    Holds the presentation source (\c{*.uia} or \c{*.uip}) file location.
+    Holds the main presentation source (\c{*.uia} or \c{*.uip}) file location.
     May be either a file URL or a qrc URL.
 */
 
 /*!
-    \qmlproperty SubPresentationSettings Presentation::subPresentationSettings
-
-    Holds the settings for the subpresentations in the Qt 3D Studio presentation.
-
-    This property is read-only.
-*/
-
-/*!
     \qmlmethod void Presentation::goToSlide(string elementPath, string name)
 
-    Requests a time context (a Scene or a Component element) to change to a specific slide
+    Requests a time context (a Scene or a Component node) to change to a specific slide
     by \a name. If the context is already on that slide playback will start over.
 
     If \a elementPath points to a time context, that element is controlled. For
@@ -516,7 +572,7 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlmethod void Presentation::goToSlide(string elementPath, int index)
 
-    Requests a time context (a Scene or a Component element) to change to a specific slide by
+    Requests a time context (a Scene or a Component node) to change to a specific slide by
     index \a index. If the context is already on that slide playback will start over.
 
     If \a elementPath points to a time context, that element is controlled. For
@@ -528,7 +584,7 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlmethod void Presentation::goToSlide(string elementPath, bool next, bool wrap)
 
-    Requests a time context (a Scene or a Component element) to change to the next or the
+    Requests a time context (a Scene or a Component node) to change to the next or the
     previous slide, depending on the value of \a next. If the context is already at the
     last or first slide, \a wrap defines if change occurs to the opposite end.
 
@@ -541,7 +597,7 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 /*!
     \qmlmethod void Presentation::goToTime(string elementPath, real time)
 
-    Sets a time context (a Scene or a Component element) to a specific playback \a time in seconds.
+    Sets a time context (a Scene or a Component node) to a specific playback \a time in seconds.
 
     If \a elementPath points to a time context, that element is controlled. For
     all other element types the time context owning that element is controlled instead.
@@ -564,88 +620,90 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
 */
 
 /*!
-    \qmlmethod void Presentation::setAttribute(string elementPath, string attributeName,
-                                               variant value)
-
-    Sets the \a value of an attribute on an element found at \a elementPath. The \a attributeName is
-    the \l{Attribute Names}{scripting name} of the attribute.
-
-    You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
-    front of the element path, for example \c{"SubPresentationOne:Scene.Mesh.Material"}.
+    \qmlmethod variant Presentation::getAttribute(string elementPath, string attributeName)
 
-    The attribute must be preserved for scripting to be set by this function, or else it will fail.
-    An attribute is preserved if it is either \e{animated}, or
-    \e{an attribute on a master element that is unlinked and changed per-slide}.
+    Returns the value of an attribute (property) on the object specified by \a
+    elementPath. The \a attributeName is the \l{Attribute Names}{scripting
+    name} of the attribute.
 */
 
 /*!
-    \qmlmethod void Presentation::setPresentationActive(string id, bool active)
-
-    Stops or starts updates to a sub-presentation based on the \a active flag. The presentation is
-    referenced to by the \a id, which is the name of the presentation without the \c{.uip}.
+    \qmlmethod void Presentation::setAttribute(string elementPath, string attributeName,
+                                               variant value)
 
-    Making a presentation inactive prevents any elements, behaviors, and animations within it from
-    updating. It also prevents any events within that presentation from being processed. It does
-    not, however, prevent the presentation from rendering. An inactive presentation will continue
-    to render using its last-updated information.
+    Sets the \a value of an attribute (property) on the Qt 3D Studio scene
+    object specified by \a elementPath. The \a attributeName is the
+    \l{Attribute Names}{scripting name} of the attribute.
 
-    Explicitly inactivating presentations can provide a significant performance increase, depending
-    on the number and size of the presentations that are inactive. Inactive presentations are not
-    ‘paused’. When the presentation is re-activated, animations will resume at the time they should
-    be had they been running, not where they were when the presentation was made inactive.
-*/
+    An element path refers to an object in the scene either by name or id. The
+    latter is rarely used in application code since the unique IDs are not
+    exposed in the Qt 3D Studio application. To refer to an object by id,
+    prepend \c{#} to the name. Applications will typically refer to objects by
+    name.
 
-/*!
-    \qmlmethod void Presentation::fireEvent(string elementPath, string eventName)
+    Names are not necessarily unique, however. To access an object with a
+    non-unique name, the path can be specified, for example,
+    \c{Scene.Layer.Camera}. Here the right camera object gets chosen even if
+    the scene contains other layers with the default camera names (for instance
+    \c{Scene.Layer2.Camera}).
 
-    Dispatches an event with \a eventName on a specific element found in \a elementPath. Appropriate
-    Appropriate actions created in Qt 3D Studio or callbacks registered using the registerForEvent()
-    method in attached scripts will be executed in response to the event.
+    If the object is renamed to a unique name in the Qt 3D Studio application's
+    Timeline view, the path can be omitted. For example, if the camera in
+    question was renamed to \c MyCamera, applications can then simply pass \c
+    MyCamera as the element path.
 
-    You can target the command to a specific sub-presentation by adding "SubPresentationId:" in
-    front of the element path, for example \c{"SubPresentationOne:Scene.Mesh"}.
+    To access an object in a sub-presentation, prepend the name of the
+    sub-presentation followed by a colon, for example,
+    \c{SubPresentationOne:Scene.Layer.Camera}.
 */
 
 /*!
-    \qmlmethod void Presentation::setGlobalAnimationTime(int64 milliseconds)
+    \qmlmethod void Presentation::fireEvent(string elementPath, string eventName)
 
-    Sets the global animation time to \a milliseconds. Setting the global animation time to a
-    non-zero value will disable the automatic animation timer. Setting the value to zero
-    resumes automatic animation timer.
+    Dispatches an event with \a eventName on a specific element found in \a
+    elementPath. Appropriate actions created in Qt 3D Studio or callbacks
+    registered using the registerForEvent() method in attached \c{behavior
+    scripts} will be executed in response to the event.
 */
 
 /*!
     \qmlmethod void Presentation::setDataInputValue(string name, variant value)
-    \since QtStudio3D 1.1
 
     Sets the \a value of a data input element \a name in the presentation.
-*/
 
-/*!
-    \qmlsignal Presentation::slideEntered(string elementPath, int index, string name)
+    Data input provides a higher level, designer-driven alternative to
+    setAttribute or Element. Instead of exposing a large set of properties with
+    their intenal engine names, data input allows designers to decide which
+    properties should be writable by the application, and can assign custom
+    names to these data input entries, thus forming a well-defined contract
+    between the designer and the developer.
 
-    This signal is emitted when a slide is entered in the presentation.
-    The \a elementPath specifies the time context (a Scene or a Component element) owning the
-    entered slide.
-    The \a index and \a name contain the index and the name of the entered slide.
+    In addition, data input also allows controlling the time line and the
+    current slide for time context objects (Scene or Component). Therefore it
+    is also an alternative to the goToSlide, goToTime, and SceneElement.
+
+    As an alternative to this method, the \l DataInput type can be used. That
+    approach has the advantage of being able to use QML property bindings for
+    the value, instead of having to resort to JavaScript function calls for
+    every value change.
 */
 
 /*!
-    \qmlsignal Presentation::slideExited(string elementPath, int index, string name)
+    \qmlsignal Presentation::slideEntered(string elementPath, int index, string name)
 
-    This signal is emitted when a slide is exited in the presentation.
-    The \a elementPath specifies the time context (a Scene or a Component element) owning the
-    exited slide.
-    The \a index and \a name contain the index and the name of the exited slide.
+    This signal is emitted when a slide is entered in the presentation. The \a
+    elementPath specifies the time context (a Scene or a Component element)
+    owning the entered slide. The \a index and \a name contain the index and
+    the name of the entered slide.
 */
 
 /*!
-    \qmlsignal Presentation::sourceChanged(url source)
-
-    This signal is emitted when the source property has changed.
-    The new value is provided in the \a source parameter.
+    \qmlsignal Presentation::slideExited(string elementPath, int index, string name)
 
-    The corresponding handler is \c onSourceChanged.
+    This signal is emitted when a slide is exited in the presentation. The \a
+    elementPath specifies the time context (a Scene or a Component element)
+    owning the exited slide. The \a index and \a name contain the index and the
+    name of the exited slide.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/api/q3dssceneelement.cpp b/src/runtime/api/q3dssceneelement.cpp
index 6b3c161..cb7482b 100644
--- a/src/runtime/api/q3dssceneelement.cpp
+++ b/src/runtime/api/q3dssceneelement.cpp
@@ -95,7 +95,7 @@ Q3DSSceneElement::~Q3DSSceneElement()
 
     \note If this property is set to something else than the default slide for
     the scene at the initial declaration of SceneElement, a changed signal for
-    the default slide may stil be emitted before the slide changes to the
+    the default slide may still be emitted before the slide changes to the
     desired one. This happens in order to ensure we end up with the index of
     the slide that is actually shown even if the slide specified in the initial
     declaration is invalid.
@@ -126,7 +126,7 @@ int Q3DSSceneElement::previousSlideIndex() const
 
     \note If this property is set to something else than the default slide for
     the scene at the initial declaration of SceneElement, a changed signal for
-    the default slide may stil be emitted before the slide changes to the
+    the default slide may still be emitted before the slide changes to the
     desired one. This happens in order to ensure we end up with the index of
     the slide that is actually shown even if the slide specified in the initial
     declaration is invalid.
@@ -252,13 +252,14 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
     \inherits Element
     \inqmlmodule QtStudio3D
     \ingroup 3dstudioruntime2
-    \brief Control type for scene and component elements in a Qt 3D Studio presentation.
 
-    This type is a convenience type for managing the slides of a single
-    time context (a Scene or a Component element) of a presentation.
+    \brief Controls the special Scene or Component scene objects in a Qt 3D
+    Studio presentation.
 
-    All methods provided by this type are queued and handled asynchronously before the next
-    frame is displayed.
+    This type is a convenience for controlling the properties of Scene
+    and Component objects in the scene. These are special since they have a
+    time context, meaning they control a timline and a set of associated
+    slides.
 
     \sa Studio3D, Presentation, Element
 */
@@ -272,11 +273,12 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
     value will not actually change until the next frame has been processed, and
     even then only if the new slide was valid.
 
-    \note If this property is set to something else than the default slide for the scene at the
-    initial declaration of SceneElement, you will still get an extra changed signal for the
-    default slide before the slide changes to the desired one. This happens in order to ensure
-    we end up with the index of the slide that is actually shown even if the slide specified in the
-    initial declaration is invalid.
+    \note If this property is set to something else than the default slide for
+    the scene at the initial declaration of SceneElement, a changed signal for
+    the default slide may still be emitted before the slide changes to the
+    desired one. This happens in order to ensure we end up with the index of
+    the slide that is actually shown even if the slide specified in the initial
+    declaration is invalid.
 */
 
 /*!
@@ -296,11 +298,12 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
     value will not actually change until the next frame has been processed, and
     even then only if the new slide was valid.
 
-    \note If this property is set to something else than the default slide for the scene at the
-    initial declaration of SceneElement, you will still get an extra changed signal for the
-    default slide before the slide changes to the desired one. This happens in order to ensure
-    we end up with the name of the slide that is actually shown even if the slide specified in the
-    initial declaration is invalid.
+    \note If this property is set to something else than the default slide for
+    the scene at the initial declaration of SceneElement, a changed signal for
+    the default slide may still be emitted before the slide changes to the
+    desired one. This happens in order to ensure we end up with the index of
+    the slide that is actually shown even if the slide specified in the initial
+    declaration is invalid.
 */
 
 /*!
@@ -358,9 +361,10 @@ void Q3DSSceneElementPrivate::setPresentation(Q3DSPresentation *pres)
 /*!
     \qmlmethod void SceneElement::goToSlide(bool next, bool wrap)
 
-    Requests a time context (a Scene or a Component element) to change to the next or the
-    previous slide, depending on the value of \a next. If the context is already at the
-    last or first slide, \a wrap defines if change occurs to the opposite end.
+    Requests a time context (a Scene or a Component object) to change to the
+    next or previous slide, depending on the value of \a next. If the context
+    is already at the last or first slide, \a wrap defines if wrapping over to
+    the first or last slide, respectively, occurs.
 */
 
 /*!
diff --git a/src/runtime/api/q3dsviewersettings.cpp b/src/runtime/api/q3dsviewersettings.cpp
index a0d91ea..d1c1013 100644
--- a/src/runtime/api/q3dsviewersettings.cpp
+++ b/src/runtime/api/q3dsviewersettings.cpp
@@ -175,9 +175,13 @@ void Q3DSViewerSettings::load(const QString &group,
 /*!
     \qmlproperty bool ViewerSettings::showRenderStats
 
-    If this property is set to \c{true}, render statistics are displayed on the upper part
-    of the viewer.
-    Default value is \c{false}.
+    If this property is set to \c true, the interactive statistics and profile
+    view is displayed in-scene, on top of the 3D content.
+
+    \note this feature can be disabled at build time, in which case this
+    property has no effect.
+
+    The default value is \c{false}.
 */
 
 QT_END_NAMESPACE
diff --git a/src/runtime/behaviorapi/q3dsbehaviorobject.cpp b/src/runtime/behaviorapi/q3dsbehaviorobject.cpp
index cf258eb..761ac2a 100644
--- a/src/runtime/behaviorapi/q3dsbehaviorobject.cpp
+++ b/src/runtime/behaviorapi/q3dsbehaviorobject.cpp
@@ -304,6 +304,11 @@ QVector3D Q3DSBehaviorObject::lookAt(const QVector3D &target)
     JavaScript. It enables interacting with the runtime using the Behavior
     QML class exposed to each behavior script.
 
+    \note the Behavior type has its own import and is only available in
+    \c{behavior scripts} that are attached to scene objects during the design
+    phase in Qt 3D Studio. It is not usable in ordinary QML
+    application code.
+
     In QML behavior script, the integration to Qt 3D Studio is established by using
     the metadata tag system similar to the \l {file-formats-effects.html}{effect}
     and \l {file-formats-material.html}{material} files.