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>

8 files changed, 134 insertions, 17 deletions

diff --git a/examples/qt3d/scene3d/doc/src/scene3d.qdoc b/examples/qt3d/scene3d/doc/src/scene3d.qdoc
index fd324e6a4..c6deb6546 100644
--- a/examples/qt3d/scene3d/doc/src/scene3d.qdoc
+++ b/examples/qt3d/scene3d/doc/src/scene3d.qdoc
@@ -33,7 +33,7 @@
 
     \image scene3d.png
 
-    \e {Scene3D} demonstrates visualizing a 3D scene from a Qt Quick
+    This example demonstrates visualizing a 3D scene from a Qt Quick
     application. The 3D scene contains a single active camera and a single
     active light source. Visualized data is assumed to be at a fixed location.
 
diff --git a/src/doc/Qt3DDoc b/src/doc/Qt3DDoc
index dbdea1700..496730dd4 100644
--- a/src/doc/Qt3DDoc
+++ b/src/doc/Qt3DDoc
@@ -21,3 +21,4 @@
 #include "../animation/frontend/qchannelmappingcreatedchange_p.h"
 #include "../animation/frontend/qclipblendnodecreatedchange_p.h"
 #include "../animation/backend/clipblendnode_p.h"
+#include "../quick3d/imports/scene3d/scene3ditem_p.h"
diff --git a/src/doc/qt3d.qdocconf b/src/doc/qt3d.qdocconf
index 90f1f2012..d4eb41601 100644
--- a/src/doc/qt3d.qdocconf
+++ b/src/doc/qt3d.qdocconf
@@ -58,7 +58,8 @@ headerdirs += . \
               ../input \
               ../extras \
               ../animation \
-              ../quick3d/quick3dscene2d
+              ../quick3d/quick3dscene2d \
+              ../quick3d/imports/scene3d
 
 # Exclude private header files from the documentation build
 excludefiles += "*_p.h"
@@ -69,7 +70,8 @@ headers       = ../core/transforms/matrix4x4_p.h \
                 ../render/raycasting/qray3d_p.h \
                 ../animation/frontend/qchannelmappingcreatedchange_p.h \
                 ../input/frontend/qabstractphysicaldeviceproxy_p.h \
-                ../input/frontend/qinputdeviceintegration_p.h
+                ../input/frontend/qinputdeviceintegration_p.h \
+                ../quick3d/imports/scene3d/scene3ditem_p.h
 
 sourcedirs += . \
               ../render \
@@ -80,7 +82,9 @@ sourcedirs += . \
               ../input \
               ../extras \
               ../animation \
-              ../quick3d/quick3dscene2d
+              ../quick3d/quick3dscene2d \
+              ../quick3d/imports/scene3d
+
 
 exampledirs += ../../examples/qt3d \
                snippets
diff --git a/src/doc/src/qt3d-module.qdoc b/src/doc/src/qt3d-module.qdoc
index cb08a60c0..2e6eff6b2 100644
--- a/src/doc/src/qt3d-module.qdoc
+++ b/src/doc/src/qt3d-module.qdoc
@@ -96,6 +96,7 @@
    import Qt3D.Extras 2.0
    import Qt3D.Animation 2.9
    import Qt3D.Scene2D 2.9
+   import Qt3D.Scene3D 2.9
    \endcode
 
    \section1 QML Types
@@ -124,4 +125,7 @@
    \section2 Qt 3D Scene2D Module
    \generatelist {qmltypesbymodule Qt3D.Scene2D}
    \noautolist
+
+   \section2 Qt 3D Scene3D Module
+   \generatelist {qmltypesbymodule Qt3D.Scene3D}
 */
diff --git a/src/doc/src/qt3dscene3d-module.qdoc b/src/doc/src/qt3dscene3d-module.qdoc
new file mode 100644
index 000000000..08cf2d371
--- /dev/null
+++ b/src/doc/src/qt3dscene3d-module.qdoc
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd and/or its subsidiary(-ies).
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt3D module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+   \qmlmodule Qt3D.Scene3D 2.0
+   \preliminary
+   \title Qt 3D Scene3D QML Types
+   \ingroup qmlmodules
+   \ingroup qt3d-qmlmodules-preliminary
+
+   \brief Provides Qt 3D QML types for the Scene3D module.
+
+   To import and use the module's QML types, use the following statement:
+
+   \badcode
+   import Qt3D.Scene3D 2.0
+   \endcode
+*/
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