more API docs

Also pull in the property name table (the up-to-dateness of which is
questionable).

The version number in the generated docs should be 2.0, not the
Qt version. Will need to figure out later how to maintain this.

Not everything is documented yet. Less important functions will get
covered later.

Many bits here and there are revised compared to the 1.1 docs.
There are however chunks that have been taken as-is. These need to be
cleaned up later on.

Most importantly, an initial Getting Started page has been added. This,
like the mobile/embedded page needs to be extended signficiantly later on.

A set of unused constructors (the ones taking no presentation) are
removed from Q3DSElement/SceneElement/DataInput. This is because
the QML API does not use them while it is impossible to utilize these
in a meaningful way from C++ (where are require setting the presentation
up-front with no setter afterwards).

There were a few qdoc warnings from the internal implementations due to
useless /*! or backslashes that confused qdoc. These are removed.

Task-number: QT3DS-1606
Change-Id: I141bdc774e5be3e4fed5c1d729cac9b68a02be3b
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

1 files changed, 50 insertions, 3 deletions

diff --git a/src/runtime/api/q3dswidget.cpp b/src/runtime/api/q3dswidget.cpp
index 6fb6d3e..8cdd898 100644
--- a/src/runtime/api/q3dswidget.cpp
+++ b/src/runtime/api/q3dswidget.cpp
@@ -44,12 +44,35 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class Q3DSWidget
-
     \inmodule 3dstudioruntime2
+    \since Qt 3D Studio 2.0
+    \inherits QOpenGLWidget
+
+    \brief A widget that renders Qt 3D Studio presentations using OpenGL.
+
+    Q3DSWidget is a widget that can be used to embed Qt 3D Studio presentations
+    into QWidget-based applications.
+
+    Q3DSWidget is used to specify a render widget for Qt 3D Studio
+    presentation. It subclasses QOpenGLWidget, which means all considerations
+    that should be taken when working with QOpenGLWidget apply to Q3DSWidget as
+    well. Refer to the QOpenGLWidget documentation for details.
+
+    \section2 Example Usage
 
-    \brief Widget
+    \code
+    Q3DSWidget *viewer = new Q3DSWidget(parentWidget);
+    viewer->presentation()->setSource(QUrl(QStringLiteral("qrc:/my_presentation.uip")));
+    viewer->setUpdateInterval(0);
 
-    blah
+    // Register a scene element object for slide management (optional)
+    Q3DSSceneElement scene(viewer->presentation(), QStringLiteral("Scene"));
+
+    // Register an element object for attribute setting (optional)
+    Q3DSElement element(viewer->presentation(), QStringLiteral("myCarModel"));
+    \endcode
+
+    \sa Q3DSSurfaceViewer
 */
 
 Q3DSWidget::Q3DSWidget(QWidget *parent)
@@ -65,12 +88,18 @@ Q3DSWidget::~Q3DSWidget()
     delete d_ptr;
 }
 
+/*!
+    Returns the presentation object used by the Q3DSWidget.
+ */
 Q3DSPresentation *Q3DSWidget::presentation() const
 {
     Q_D(const Q3DSWidget);
     return d->presentation;
 }
 
+/*!
+    Returns the settings object used by the Q3DSWidget.
+ */
 Q3DSViewerSettings *Q3DSWidget::settings() const
 {
     Q_D(const Q3DSWidget);
@@ -83,12 +112,30 @@ QString Q3DSWidget::error() const
     return d->error;
 }
 
+/*!
+    \property Q3DSWidget::running
+
+    The value of this property is \c true when the viewer has been initialized
+    and the presentation is running.
+
+    This property is read-only.
+*/
 bool Q3DSWidget::isRunning() const
 {
     Q_D(const Q3DSWidget);
     return d->engine && d->sourceLoaded;
 }
 
+/*!
+    \property Q3DSWidget::updateInterval
+
+    Holds the viewer update interval in milliseconds. If the value is negative,
+    the viewer doesn't update the presentation automatically.
+
+    The default value is 0, meaning automatic updates are enabled.
+
+    \sa QWidget::update()
+*/
 int Q3DSWidget::updateInterval() const
 {
     Q_D(const Q3DSWidget);