Doc: Add basic documentation for Scene3D QML module

Adds Scene3D as QML module.
Provides preliminary documentation for Scene3D QML type.

Task-number: QTBUG-61651
Task-number: QTBUG-54816
Change-Id: I2811bb2165ca0adde574ddde70fa7185b3c03083
Reviewed-by: Laszlo Agocs <laszlo.agocs@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

3 files changed, 67 insertions, 13 deletions

diff --git a/src/quick3d/imports/scene3d/scene3ditem.cpp b/src/quick3d/imports/scene3d/scene3ditem.cpp
index 2c20fa789..740fda294 100644
--- a/src/quick3d/imports/scene3d/scene3ditem.cpp
+++ b/src/quick3d/imports/scene3d/scene3ditem.cpp
@@ -72,17 +72,33 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DRender {
 
 /*!
-    \class Qt3DCore::Scene3DItem
+    \class Qt3DRender::Scene3DItem
     \internal
 
-    \brief The Qt3DCore::Scene3DItem class is a QQuickItem subclass used to integrate
+    \brief The Scene3DItem class is a QQuickItem subclass used to integrate
     a Qt3D scene into a QtQuick 2 scene.
 
-    The Qt3DCore::Scene3DItem class renders a Qt3D scene, provided by a Qt3DCore::QEntity
-    into a multisampled Framebuffer object that is later blitted into a non
-    multisampled Framebuffer object to be then renderer through the use of a
+    The Scene3DItem class renders a Qt3D scene, provided by a Qt3DCore::QEntity
+    into a multisampled Framebuffer object that is later blitted into a
+    non-multisampled Framebuffer object to be then rendered through the use of a
     Qt3DCore::Scene3DSGNode with premultiplied alpha.
  */
+
+/*!
+    \qmltype Scene3D
+    \inherits Item
+    \inqmlmodule Qt3D.Scene3D
+
+    \preliminary
+
+    \brief The Scene3D type is used to integrate a Qt3D scene into a QtQuick 2
+    scene.
+
+    The Scene3D type renders a Qt3D scene, provided by an \l Entity, into a
+    multisampled Framebuffer object. This object is later blitted into a
+    non-multisampled Framebuffer object, which is then rendered with
+    premultiplied alpha.
+ */
 Scene3DItem::Scene3DItem(QQuickItem *parent)
     : QQuickItem(parent)
     , m_entity(nullptr)
@@ -105,11 +121,23 @@ Scene3DItem::~Scene3DItem()
     // Scene3DSGNode still exist and will perform their cleanup on their own.
 }
 
+/*!
+    \qmlproperty list<string> Scene3D::aspects
+
+    \brief \TODO
+    */
 QStringList Scene3DItem::aspects() const
 {
     return m_aspects;
 }
 
+/*!
+    \qmlproperty Entity Scene3D::entity
+
+    \default
+
+    \brief \TODO
+ */
 Qt3DCore::QEntity *Scene3DItem::entity() const
 {
     return m_entity;
@@ -177,6 +205,16 @@ void Scene3DItem::setHoverEnabled(bool enabled)
     }
 }
 
+/*!
+    \qmlproperty enumeration Scene3D::cameraAspectRatioMode
+
+    \value Scene3D.AutomaticAspectRatio
+           Automatic aspect ratio.
+
+    \value Scene3D.UserAspectRatio
+           User defined aspect ratio.
+    \brief \TODO
+ */
 Scene3DItem::CameraAspectRatioMode Scene3DItem::cameraAspectRatioMode() const
 {
     return m_cameraAspectRatioMode;
@@ -240,7 +278,11 @@ void Scene3DItem::setWindowSurface(QObject *rootObject)
         }
     }
 }
+/*!
+    \qmlmethod void Scene3D::setItemAreaAndDevicePixelRatio(size area, real devicePixelRatio)
 
+    \brief \TODO
+ */
 void Scene3DItem::setItemAreaAndDevicePixelRatio(QSize area, qreal devicePixelRatio)
 {
     Qt3DRender::QRenderSurfaceSelector *surfaceSelector = Qt3DRender::QRenderSurfaceSelectorPrivate::find(m_entity);
@@ -250,6 +292,11 @@ void Scene3DItem::setItemAreaAndDevicePixelRatio(QSize area, qreal devicePixelRa
     }
 }
 
+/*!
+    \qmlproperty bool Scene3D::hoverEnabled
+
+    \c true if hover events are accepted.
+ */
 bool Scene3DItem::isHoverEnabled() const
 {
     return acceptHoverEvents();
@@ -280,6 +327,11 @@ void Scene3DItem::updateCameraAspectRatio()
 }
 
 /*!
+    \qmlproperty bool Scene3D::multisample
+
+    \c true if a multi-sample render buffer is in use.
+ */
+/*!
     \return \c true if a multisample renderbuffer is in use.
  */
 bool Scene3DItem::multisample() const
diff --git a/src/quick3d/imports/scene3d/scene3drenderer.cpp b/src/quick3d/imports/scene3d/scene3drenderer.cpp
index 4822c7bc4..b3cac0dcd 100644
--- a/src/quick3d/imports/scene3d/scene3drenderer.cpp
+++ b/src/quick3d/imports/scene3d/scene3drenderer.cpp
@@ -92,17 +92,18 @@ private:
 };
 
 /*!
-    \class Qt3DCore::Scene3DRenderer
+    \class Qt3DRender::Scene3DRenderer
     \internal
 
-    \brief The Qt3DCore::Scene3DRenderer class takes care of rendering a Qt3D scene
+    \brief The Scene3DRenderer class takes care of rendering a Qt3D scene
     within a Framebuffer object to be used by the QtQuick 2 renderer.
 
-    The Qt3DCore::Scene3DRenderer class renders a Qt3D scene as provided by a Qt3DCore::Scene3DItem.
+    The Scene3DRenderer class renders a Qt3D scene as provided by a Scene3DItem.
     It owns the aspectEngine even though it doesn't instantiate it.
 
     The shutdown procedure is a two steps process that goes as follow:
 
+    \list
     \li The window is closed
 
     \li This triggers the windowsChanged signal which the Scene3DRenderer
@@ -112,6 +113,7 @@ private:
     \li The destroyed signal of the window is also connected to the
     Scene3DRenderer. When triggered in the context of the main thread, the
     cleanup slot is called.
+    \endlist
 
     There is an alternate shutdown procedure in case the QQuickItem is
     destroyed with an active window which can happen in the case where the
diff --git a/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp b/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp
index a47d00268..1b8b08a4e 100644
--- a/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp
+++ b/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp
@@ -44,14 +44,14 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DRender {
 
 /*!
-    \class Qt3DCore::Scene3DSGMaterial
+    \class Qt3DRender::Scene3DSGMaterial
     \internal
-    \inherit QSGMaterial
+    \inherits QSGMaterial
 
-    \brief The Qt3DRender::Scene3DSGMaterial class is a custom QSGMaterial subclass used to
-    render a Qt3DRender::Scene3DSGNode
+    \brief The Scene3DSGMaterial class is a custom QSGMaterial subclass used to
+    render a Scene3DSGNode
 
-    The Qt3DRender::Scene3DSGMaterial class renders a texture using premultiplied
+    The Scene3DSGMaterial class renders a texture using premultiplied
     alpha unlike the QSGSimpleTextureMaterial.
 
     This is needed to properly integrate alpha blending from a Qt3D scene