Added documentation for the planets-qml example

Change-Id: I07734c6a30f49b05cd7815d3c3412cd867a09836
Task-number: QTBUG-46602
Reviewed-by: Mika Salmela <mika.salmela@theqtcompany.com>
Reviewed-by: Titta Heikkala <titta.heikkala@theqtcompany.com>
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@theqtcompany.com>
(cherry picked from commit fc662e5a4597b568561c3a19abb24151086a229d)

5 files changed, 87 insertions, 2 deletions

diff --git a/examples/qt3d/planets-qml/PlanetsMain.qml b/examples/qt3d/planets-qml/PlanetsMain.qml
index 3c8ab417b..84705e696 100644
--- a/examples/qt3d/planets-qml/PlanetsMain.qml
+++ b/examples/qt3d/planets-qml/PlanetsMain.qml
@@ -50,6 +50,7 @@ Item {
         anchors.fill: parent
         color: "black"
 
+        //! [0]
         Scene3D {
             anchors.fill: parent
             anchors.margins: 10
@@ -58,6 +59,7 @@ Item {
 
             SolarSystem { id: solarsystem }
         }
+        //! [0]
 
         MouseArea {
             anchors.fill: parent
@@ -71,6 +73,7 @@ Item {
         }
     }
 
+    //! [1]
     onFocusedPlanetChanged: {
         solarsystem.setFreeCamera(false)
         if (focusedPlanet == 100) {
@@ -84,6 +87,7 @@ Item {
         solarsystem.changePlanetFocus(oldPlanet, focusedPlanet)
         oldPlanet = focusedPlanet
     }
+    //! [1]
 
     ListModel {
         id: planetModel
@@ -285,7 +289,9 @@ Item {
         value: 1
         minimumValue: 1
         maximumValue: 2
+        //! [2]
         onValueChanged: solarsystem.changeCameraDistance(value)
+        //! [2]
     }
     Text {
         y: distanceSlider.y + distanceSlider.height + width + 10
diff --git a/examples/qt3d/planets-qml/SolarSystem.qml b/examples/qt3d/planets-qml/SolarSystem.qml
index 339643235..d34627735 100644
--- a/examples/qt3d/planets-qml/SolarSystem.qml
+++ b/examples/qt3d/planets-qml/SolarSystem.qml
@@ -156,6 +156,7 @@ Entity {
         light: light
     }
 
+    //! [2]
     QQ2.Component.onCompleted: {
         planetData = Planets.loadPlanetData()
         // Push in the correct order
@@ -181,7 +182,9 @@ Entity {
         changeSpeed(0.2)
         setLookAtOffset(Planets.SUN)
     }
+    //! [2]
 
+    //! [0]
     QQ2.NumberAnimation {
         id: lookAtOffsetAnimation
         target: sceneRoot
@@ -199,6 +202,7 @@ Entity {
         easing.type: Easing.InOutQuint
         duration: 2500
     }
+    //! [0]
 
     QQ2.Behavior on cameraNear {
         QQ2.PropertyAnimation {
@@ -408,6 +412,7 @@ Entity {
         cameraDistance = distance
     }
 
+    //! [3]
     function animate(focusedPlanet) {
         if (!ready || freeCamera)
             return
@@ -418,6 +423,7 @@ Entity {
 
         updateCamera(focusedPlanet)
     }
+    //! [3]
 
     function updateCamera(focusedPlanet) {
         // Get the appropriate near plane position for the camera and animate it with QML animations
@@ -602,6 +608,7 @@ Entity {
 
     // EARTH
 
+    //! [1]
     Planet {
         id: earth
         tilt: planetData[Planets.EARTH].tilt
@@ -639,6 +646,7 @@ Entity {
 
         components: [ earth, materialEarth, transformEarth ]
     }
+    //! [1]
 
     // EARTH CLOUDS
 
diff --git a/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg b/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg
new file mode 100644
index 000000000..d388d5ee4
--- /dev/null
+++ b/examples/qt3d/planets-qml/doc/images/planets-qml-example.jpg
diff --git a/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc b/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc
index d03e11325..d68a21b2d 100644
--- a/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc
+++ b/examples/qt3d/planets-qml/doc/src/planets-qml.qdoc
@@ -38,7 +38,76 @@
     \example planets-qml
     \title Qt3D: Planets QML Example
     \ingroup qt3d-examples-qml
+    \brief Demonstrates combining Qt 3D rendering and Qt Quick 2 elements.
 
-    TODO
+    The Planets example demonstrates how to implement an application that combines the use of
+    Qt 3D rendering with Qt Quick 2D elements. The example shows the eight planets of our Solar
+    System with the Sun.
 
+    \image planets-qml-example.jpg
+
+    Planet texture maps are Copyright (c) by James Hastings-Trew
+    \l{http://planetpixelemporium.com/planets.html}{http://planetpixelemporium.com/planets.html}
+    used with permission.
+
+    The planets are rotating around the Sun based on their orbit at a given time. The rotation
+    starts at 2000 Jan 0.0 UT. The planet positions are calculated based on the formulas found here:
+    \l {http://www.stjarnhimlen.se/comp/ppcomp.html}{http://www.stjarnhimlen.se/comp/ppcomp.html}
+    and \l {http://www.davidcolarusso.com/astro/}{http://www.davidcolarusso.com/astro/}.
+
+    \section1 Qt Quick 2D Implementation
+
+    The Qt Quick Implementation \l{planets-qml/PlanetsMain.qml}{PlanetsMain.qml} of the
+    example renders the 3D content using the \c Scene3D type.
+
+    \snippet planets-qml/PlanetsMain.qml 0
+
+    The planet related information is stored into a \c{ListModel}. The selection buttons for the
+    planets and the information sheet are created based on the model. The 2D elements, selection
+    buttons and sliders, are implemented in the \l{planets-qml/PlanetsMain.qml}{PlanetsMain.qml}.
+
+    The selection buttons change the \c{focusedPlanet} property of the \c{mainview}. As the property
+    changes, the planet information is updated, and the camera is animated to the new position.
+
+    \snippet planets-qml/PlanetsMain.qml 1
+
+    The camera position and the camera look at point are updated based on values that are animated
+    in the \l{planets-qml/SolarSystem.qml}{SolarSystem.qml}, triggered from the
+    \c{changePlanetFocus()} function.
+
+    \snippet planets-qml/SolarSystem.qml 0
+
+    The sliders are used to adjust the rotation speed, the planet size, and the viewing distance.
+    When a slider value changes, a JavaScript function in \l{planets-qml/SolarSystem.qml}
+    {SolarSystem.qml} is called to adjust the given property. For example, changing the value of
+    the \e{Viewing Distance} slider calls the \c{changeCameraDistance()} method.
+
+    \snippet planets-qml/PlanetsMain.qml 2
+
+    \section1 Qt 3D Implementation
+
+    The main part of the implementation, including the movement and rotation maths for the planets,
+    is done in the \l{planets-qml/SolarSystem.qml}{SolarSystem.qml}.
+
+    First, a \c Camera, a \c{Light}, and a \c Configuration are added, followed by \c{Effect}s for
+    the planet \c{Material}s, and finally the planets themselves. For example, Earth is constructed
+    as follows:
+
+    \snippet planets-qml/SolarSystem.qml 1
+
+    Planet data, which is needed for the movement and rotation calculations, among other things, is
+    constructed with JavaScript in \l{planets-qml/planets.js}{planets.js} by calling
+    \c{loadPlanetData()} as the component completes. Other initializations, such as inserting the
+    planets into an array for easier handling, calculating the ring radii for Saturn and Uranus
+    rings, and setting the default scale, speed and camera offset, are done as well:
+
+    \snippet planets-qml/SolarSystem.qml 2
+
+    The scene is animated by calling the \c{animate()} function. That is also the place where the
+    time is advanced, and the new positions for all of the planets are calculated. The planets are
+    rotated in the \c{positionPlanet()} function based on their axial tilt and their sidereal
+    rotation period. Finally, the new camera position is calculated in the \c{updateCamera()}
+    function.
+
+    \snippet planets-qml/SolarSystem.qml 3
 */
diff --git a/examples/qt3d/planets-qml/planets-qml.pro b/examples/qt3d/planets-qml/planets-qml.pro
index f2ebf1f1b..7c27fc579 100644
--- a/examples/qt3d/planets-qml/planets-qml.pro
+++ b/examples/qt3d/planets-qml/planets-qml.pro
@@ -10,7 +10,9 @@ SOURCES += \
 OTHER_FILES += \
     *.qml \
     planets.js \
-    shaders\*.*
+    shaders/*.* \
+    doc/src/*.* \
+    doc/images/*.*
 
 RESOURCES += \
     planets-qml.qrc \