Doc: QSceneLoader add detailed description

Change-Id: Ida051e80dcd76c687fe8bf475df2934449d3dd4a
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

1 files changed, 50 insertions, 4 deletions

diff --git a/src/render/io/qsceneloader.cpp b/src/render/io/qsceneloader.cpp
index 215f8edd0..2d0c3311c 100644
--- a/src/render/io/qsceneloader.cpp
+++ b/src/render/io/qsceneloader.cpp
@@ -67,6 +67,28 @@ QSceneLoaderPrivate::QSceneLoaderPrivate()
 
   \brief Provides the facility to load an existing Scene
 
+  Given a 3D source file, the Qt3DRender::QSceneLoader will try to parse it and
+  build a tree of Qt3DCore::QEntity with proper Qt3DRender::QGeometryRenderer
+  Qt3DCore::QTransform and QtRender::QMaterial components.
+
+  The loader will try to determine the best material to be used based on the properties
+  of the model file. If you wish to use a custom material, you will have to traverse
+  the tree and replace the default associated materials with yours.
+
+  As the name implies, Qt3DRender::QSceneLoader loads a complete scene subtree.
+  If you wish to load a single piece of geometry, you should rather be using
+  the Qt3DRender::QMesh instead.
+
+  Qt3DRender::QSceneLoader internally relies on the use of plugins to support a
+  wide variety of 3D file formats. \l
+  {http://www.assimp.org/main_features_formats.html}{Here} is a list of formats
+  that are supported by Qt3D.
+
+  \note this component shouldn't be shared among several Qt3DCore::QEntity instances.
+  Undefined behavior will result.
+
+  \sa Qt3DRender::QMesh
+  \sa Qt3DRender::QGeometryRenderer
  */
 
 /*!
@@ -76,16 +98,40 @@ QSceneLoaderPrivate::QSceneLoaderPrivate()
     \inherits Component
     \since 5.7
     \qmlabstract Provides the facility to load an existing Scene
+
+    Given a 3D source file, the SceneLoader will try to parse it and build a
+    tree of Entity with proper GeometryRenderer, Transform and Material
+    components.
+
+    The loader will try to determine the best material to be used based on the
+    properties of the model file. If you wish to use a custom material, you
+    will have to traverse the tree and replace the default associated materials
+    with yours.
+
+    As the name implies, SceneLoader loads a complete scene subtree. If you
+    wish to load a single piece of geometry, you should rather be using the
+    Mesh instead.
+
+    SceneLoader internally relies on the use of plugins to support a wide
+    variety of 3D file formats. \l
+    {http://www.assimp.org/main_features_formats.html}{Here} is a list of
+    formats that are supported by Qt3D.
+
+    \note this component shouldn't be shared among several Entity instances.
+    Undefined behavior will result.
+
+    \sa Mesh
+    \sa GeometryRenderer
 */
 
 /*!
     \enum QSceneLoader::Status
 
     This enum identifies the state of loading
-    \value None
-    \value Loading
-    \value Ready
-    \value Error
+    \value None     The Qt3DRender::QSceneLoader hasn't been used yet.
+    \value Loading  The Qt3DRender::QSceneLoader is currently loading the scene file.
+    \value Ready    The Qt3DRender::QSceneLoader successfully loaded the scene file.
+    \value Error    The Qt3DRender::QSceneLoader encountered an error while loading the scene file.
 */
 
 /*!