Update and fix documentation

Also move d_ptr variable to private in Q3DSDataInput.

Task-id: QT3DS-4050
Change-Id: I91ded90a413e0e9f78b0d866823a686357e4b908
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

9 files changed, 81 insertions, 76 deletions

diff --git a/src/api/studio3d/doc/qt3dstudio-opengl-runtime-project.qdocconf b/src/api/studio3d/doc/qt3dstudio-opengl-runtime-project.qdocconf
index ece96a5..3e8de94 100644
--- a/src/api/studio3d/doc/qt3dstudio-opengl-runtime-project.qdocconf
+++ b/src/api/studio3d/doc/qt3dstudio-opengl-runtime-project.qdocconf
@@ -15,7 +15,7 @@ headerdirs              += ../.. \
 
 imagedirs               += ./src/images
 
-depends = qtcore qtgui qtwidgets qtqml qtquick qtquickcontrols qt3dstudio qt3dstudioruntime2 qtdoc qmake
+depends = qtcore qtgui qtwidgets qtqml qtquick qtquickcontrols qtdoc qmake
 
 qhp.projects            = QtStudio3D
 
@@ -55,9 +55,7 @@ buildversion                   = "Qt 3D Studio OpenGL Runtime $QT_VER Manual"
 
 macro.RUNTIME                  = Qt 3D Studio OpenGL Runtime
 
-#TODO: adjust these once we have runtime-specific examples
-# examplesinstallpath     = studio3d
-# exampledirs            += ../examples/studio3d
+examplesinstallpath     = studio3d
+exampledirs            += ../../../../examples/studio3d
 
 Cpp.ignoretokens     += Q3DSV_EXPORT Q_STUDIO3D_EXPORT
-depends += qt3d
diff --git a/src/api/studio3d/doc/src/gettingstarted.qdoc b/src/api/studio3d/doc/src/gettingstarted.qdoc
index 9289b54..a80c919 100644
--- a/src/api/studio3d/doc/src/gettingstarted.qdoc
+++ b/src/api/studio3d/doc/src/gettingstarted.qdoc
@@ -68,10 +68,7 @@
 
     \li Qt Quick: here applications import QtStudio3D.OpenGL \QtVer which
     provides the \l [QML] Studio3D QML type, a Qt Quick item that can be
-    added to Qt Quick scenes. Under the hood this is similar to adding a
-    \l [QML] Scene3D (when working directly with the lower level Qt 3D
-    framework) or a custom item based on \l QQuickFramebufferObject into
-    the scene.
+    added to Qt Quick scenes.
 
     \li QWindow or offscreen render targets (OpenGL texture): Q3DSSurfaceViewer
     can be used both to render to an on-screen QWindow, as well as off-screen
diff --git a/src/api/studio3d/q3dsdatainput.cpp b/src/api/studio3d/q3dsdatainput.cpp
index 232fd0e..c98e6b4 100644
--- a/src/api/studio3d/q3dsdatainput.cpp
+++ b/src/api/studio3d/q3dsdatainput.cpp
@@ -112,10 +112,6 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \dontdocument QMetaTypeId
-*/
-
-/*!
     \internal
  */
 Q3DSDataInput::Q3DSDataInput(QObject *parent)
@@ -410,28 +406,6 @@ void Q3DSDataInputPrivate::setCommandQueue(CommandQueue *queue)
 }
 
 /*!
-    \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,
-    although it is changeable afterwards, if desired.
-*/
-
-/*!
-    \qmlproperty variant DataInput::value
-
-    Specifies the value of the controlled data input element in the presentation.
-
-    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.
-*/
-
-/*!
     \qmlproperty real DataInput::min
 
     Contains the minimum value of the controlled data input element range.
@@ -461,4 +435,18 @@ void Q3DSDataInputPrivate::setCommandQueue(CommandQueue *queue)
     \note This value is read-only.
 */
 
+/*!
+    \property Q3DSDataInput::metadataKeys
+
+    Contains the metadata keys specified for this datainput.
+
+    \note This value is read-only.
+*/
+
+/*!
+    \qmlmethod list<string> DataInput::metadataKeys
+
+    Contains the metadata keys specified for this datainput.
+*/
+
 QT_END_NAMESPACE
diff --git a/src/api/studio3d/q3dsdatainput.h b/src/api/studio3d/q3dsdatainput.h
index 8d6cff7..0465b43 100644
--- a/src/api/studio3d/q3dsdatainput.h
+++ b/src/api/studio3d/q3dsdatainput.h
@@ -77,10 +77,10 @@ Q_SIGNALS:
 protected:
     explicit Q3DSDataInput(Q3DSDataInputPrivate *d, Q3DSPresentation *presentation,
                            const QString &name, QObject *parent = nullptr);
-    Q3DSDataInputPrivate *d_ptr;
 
 private:
     Q_DISABLE_COPY(Q3DSDataInput)
+    Q3DSDataInputPrivate *d_ptr;
     friend class Q3DSPresentationPrivate;
     friend class Q3DSPresentation;
     friend class Q3DSRenderer;
diff --git a/src/api/studio3d/q3dsgeometry.cpp b/src/api/studio3d/q3dsgeometry.cpp
index f4b650a..d8bc463 100644
--- a/src/api/studio3d/q3dsgeometry.cpp
+++ b/src/api/studio3d/q3dsgeometry.cpp
@@ -287,7 +287,9 @@ void Q3DSGeometry::addAttribute(Q3DSGeometry::Attribute::Semantic semantic,
 }
 
 /*!
-    This is an overloaded function.
+    Sets an attribute \a att to this geometry.
+
+    \sa addAttribute
  */
 void Q3DSGeometry::addAttribute(const Q3DSGeometry::Attribute &att)
 {
diff --git a/src/api/studio3d/q3dspresentation.cpp b/src/api/studio3d/q3dspresentation.cpp
index 3b02e01..0270e42 100644
--- a/src/api/studio3d/q3dspresentation.cpp
+++ b/src/api/studio3d/q3dspresentation.cpp
@@ -91,7 +91,6 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \qmltype Presentation
-    \instantiates Q3DSPresentationItem
     \inqmlmodule QtStudio3D.OpenGL
     \ingroup OpenGLRuntime
     \inherits Q3DSPresentation
@@ -733,7 +732,7 @@ void Q3DSPresentation::exportShaderCache(QByteArray &cacheData, bool binaryShade
 
 /*!
     \since Qt 3D Studio 2.6
-    Specifies the shader cache data to be used for initial shader initialization.
+    Specifies the \a shaderCache data to be used for initial shader initialization.
     This method must be called before the presentation is shown.
     Using cached shaders improves presentation initialization speed.
 
@@ -1162,8 +1161,8 @@ void Q3DSPresentation::createElement(const QString &parentElementPath, const QSt
     specified with \a slideName. Element properties are specified in \a properties.
     For more details, see createElement().
 
-    \sa createElement()
-    \sa elementsCreated()
+    \sa Q3DSPresentation::createElement()
+    \sa Q3DSPresentation::elementsCreated()
  */
 void Q3DSPresentation::createElements(const QString &parentElementPath, const QString &slideName,
                                       const QVector<QHash<QString, QVariant>> &properties)
@@ -1224,8 +1223,8 @@ void Q3DSPresentation::deleteElements(const QStringList &elementPaths)
 
     \note Elements can only be dynamically created via C++ API.
 
-    \sa createElement()
-    \sa createElements()
+    \sa Q3DSPresentation::createElement()
+    \sa Q3DSPresentation::createElements()
 */
 
 /*!
@@ -1360,9 +1359,6 @@ void Q3DSPresentation::deleteMaterials(const QStringList &materialNames)
     This property is read-only.
 
     \note Materials can only be dynamically created via C++ API.
-
-    \sa createMaterial()
-    \sa createMaterials()
 */
 
 /*!
@@ -1475,9 +1471,6 @@ void Q3DSPresentation::deleteMeshes(const QStringList &meshNames)
     This property is read-only.
 
     \note Meshes can only be dynamically created via C++ API.
-
-    \sa createMesh()
-    \sa createMeshes()
 */
 
 /*!
@@ -1691,8 +1684,7 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 
     If creation failed, \a error string indicates the reason.
 
-    \sa createElement()
-    \sa createElements()
+    \note Elements can only be dynamically created via C++ API.
  */
 
 /*!
@@ -1716,8 +1708,7 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 
     If creation failed, \a error string indicates the reason.
 
-    \sa createMaterial()
-    \sa createMaterials()
+    \note Materials can only be dynamically created via C++ API.
  */
 
 /*!
@@ -1742,8 +1733,7 @@ void Q3DSPresentation::keyReleaseEvent(QKeyEvent *e)
 
     If creation failed, \a error string indicates the reason.
 
-    \sa createMesh()
-    \sa createMeshes()
+    \note Meshes can only be dynamically created via C++ API.
  */
 
 /*!
diff --git a/src/api/studio3d/q3dssurfaceviewer.cpp b/src/api/studio3d/q3dssurfaceviewer.cpp
index 401cb8f..e541e02 100644
--- a/src/api/studio3d/q3dssurfaceviewer.cpp
+++ b/src/api/studio3d/q3dssurfaceviewer.cpp
@@ -98,7 +98,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
  * \brief Q3DSSurfaceViewer::Q3DSSurfaceViewer Constructor.
- * \param parent Optional parent of the object.
+ * \a parent Optional parent of the object.
  */
 Q3DSSurfaceViewer::Q3DSSurfaceViewer(QObject *parent)
     : QObject(parent)
@@ -277,6 +277,14 @@ int Q3DSSurfaceViewer::fboId() const
 }
 
 /*!
+    \property Q3DSSurfaceViewer::error
+
+    Error string.
+
+    This property is read-only.
+*/
+
+/*!
     Returns the error string.
 */
 QString Q3DSSurfaceViewer::error() const
@@ -378,6 +386,12 @@ void Q3DSSurfaceViewer::setQmlEngine(QQmlEngine *qmlEngine)
  */
 
 /*!
+    \fn Q3DSSurfaceViewer::afterRendering()
+
+    Emitted when a frame has been rendered.
+ */
+
+/*!
  * \internal
  */
 Q3DSSurfaceViewerPrivate::Q3DSSurfaceViewerPrivate(Q3DSSurfaceViewer *q)
diff --git a/src/api/studio3d/q3dsviewersettings.cpp b/src/api/studio3d/q3dsviewersettings.cpp
index 7aa11a2..dd8e4b2 100644
--- a/src/api/studio3d/q3dsviewersettings.cpp
+++ b/src/api/studio3d/q3dsviewersettings.cpp
@@ -96,6 +96,15 @@ Q3DSViewerSettings::~Q3DSViewerSettings()
 */
 
 /*!
+    \enum Q3DSViewerSettings::ShadeMode
+
+    This enumeration specifies the possible shading modes.
+
+    \value ShadeModeShaded Shades the surfaces normally. This is the default.
+    \value ShadeModeShadedWireframe Renders wireframe on top of shaded surfaces.
+*/
+
+/*!
     \qmlproperty QColor ViewerSettings::matteColor
 
     Specifies the matte color.
@@ -155,17 +164,18 @@ void Q3DSViewerSettings::setShowRenderStats(bool show)
     }
 }
 
-/*
-    //! TODO
-    \internal
-    \qmlproperty enumeration ViewerSettings::shadeMode
- */
+/*!
+    \fn Q3DSViewerSettings::shadeModeChanged(ShadeMode mode)
 
-/*
-    // TODO
-    \internal
-    \property Q3DSViewerSettings::shadeMode
+    Emitted when shade \a mode is changed.
+*/
+
+/*!
+    Returns the shading mode used.
+
+    \sa Q3DSViewerSettings::ShadeMode
  */
+
 Q3DSViewerSettings::ShadeMode Q3DSViewerSettings::shadeMode() const
 {
     return d_ptr->m_shadeMode;
@@ -200,21 +210,13 @@ void Q3DSViewerSettings::setShadeMode(Q3DSViewerSettings::ShadeMode mode)
 /*!
     \property Q3DSViewerSettings::scaleMode
 
-    Specifies the scaling mode. The default value \c is ScaleModeFill where the
-    size of the presentation on-screen follows and fills the size of the output
-    area (the window, the screen, or the area occupied by the \l Studio3D
-    element).
-
-    During the design phase it can be valuable to see the presentation with
-    some other scaling approach. For example, the Qt 3D Studio Viewer
-    application uses ScaleModeCenter by default.
+    Specifies the scaling mode.
 
     \value ScaleModeFit Scales the presentation to fit the output area.
     \value ScaleModeFill Scales the presentation to completely fill the output area.
     \value ScaleModeCenter Centers the presentation in the output area without scaling it.
+*/
 
-    The default value is \c{ScaleModeFill}.
- */
 Q3DSViewerSettings::ScaleMode Q3DSViewerSettings::scaleMode() const
 {
     return d_ptr->m_scaleMode;
@@ -262,6 +264,20 @@ void Q3DSViewerSettings::setScaleMode(Q3DSViewerSettings::ScaleMode mode)
 
     The default value is \c{StereoModeMono}.
  */
+
+/*!
+    \enum Q3DSViewerSettings::StereoMode
+
+    \since Qt 3D Studio 2.5
+
+    This enumeration specifies the possible stereoscopic viewing modes.
+
+    \value StereoModeMono This is the default value.
+    \value StereoModeTopBottom
+    \value StereoModeLeftRight
+    \value StereoModeAnaglyphRedCyan
+    \value StereoModeAnaglyphGreenMagenta
+*/
 Q3DSViewerSettings::StereoMode Q3DSViewerSettings::stereoMode() const
 {
     return d_ptr->m_stereoMode;
diff --git a/src/qmlstreamer/q3dsqmlstream.cpp b/src/qmlstreamer/q3dsqmlstream.cpp
index c0dc6a2..bea6610 100644
--- a/src/qmlstreamer/q3dsqmlstream.cpp
+++ b/src/qmlstreamer/q3dsqmlstream.cpp
@@ -36,7 +36,7 @@
     \ingroup OpenGLRuntime
     \brief Allows streaming of QML as subpresentation.
 
-    \sa Studio3D, Presentation, SubPresentation
+    \sa Studio3D, Presentation
 */
 /*!
     \class Q3DSQmlStream