Update QTextureImage docs

Update QTextureImage docs and add documentation for
QTextureImageDataGenerator and QAbstractFunctor

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

3 files changed, 137 insertions, 21 deletions

diff --git a/src/render/frontend/qabstractfunctor.cpp b/src/render/frontend/qabstractfunctor.cpp
index f3367a2b5..817d06a27 100644
--- a/src/render/frontend/qabstractfunctor.cpp
+++ b/src/render/frontend/qabstractfunctor.cpp
@@ -43,8 +43,44 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DRender {
 
+/*!
+    \class Qt3DRender::QAbstractFunctor
+    \inmodule Qt3DRender
+    \since 5.7
+    \brief QAbstractFunctor is an abstract base class for all functors.
+
+    The QAbstractFunctor is used as a base class for all functors and data
+    generators in Qt3DRender module.
+
+    When user defines a new functor or generator, they need to implement the
+    \l QAbstractFunctor::id() method, which should be done using the \c {QT3D_FUNCTOR}
+    macro in the class definition.
+ */
+/*!
+    \fn qintptr QAbstractFunctor::id() const
+ */
+/*!
+    \macro QT3D_FUNCTOR(Class)
+    \relates Qt3DRender::QAbstractFunctor
+
+    This macro assigns functor id to the \a Class, which is used by QAbstractFunctor::functor_cast
+    to determine if the cast can be done.
+ */
+
+/*!
+    \fn const T *QAbstractFunctor::functor_cast(const QAbstractFunctor *other) const
+
+    This method is used to cast functor \a other to type T if the other is of
+    type T (or of subclass); otherwise returns 0. This method works similarly
+    to \l QObject::qobject_cast, except with functors derived from QAbstractFunctor.
+
+    \warning If T was not declared with \l QT3D_FUNCTOR macro, then the results are undefined.
+  */
+
+/*! Desctructor */
 QAbstractFunctor::~QAbstractFunctor()
 {
+
 }
 
 } // Qt3D
diff --git a/src/render/texture/qabstracttextureimage.cpp b/src/render/texture/qabstracttextureimage.cpp
index d3694efc9..42e78ced6 100644
--- a/src/render/texture/qabstracttextureimage.cpp
+++ b/src/render/texture/qabstracttextureimage.cpp
@@ -48,6 +48,40 @@ using namespace Qt3DCore;
 
 namespace Qt3DRender {
 
+/*!
+    \class Qt3DRender::QTextureImageDataGenerator
+    \inmodule Qt3DRender
+    \since 5.7
+    \brief Provides texture image data for QAbstractTextureImage
+
+    QTextureImageDataGenerator is a data provider for QAbstractTexture.
+    QTextureImageDataGenerator can be used to expand Qt3D with more ways to load
+    texture image data as well as support user-defined formats and formats Qt3D
+    does not natively support. The data is returned by the QTextureImageDataPtr
+    which contains the data that will be loaded to the texture.
+    QTextureImageDataGenerator is executed by Aspect jobs in the backend.
+ */
+/*!
+    \typedef Qt3DRender::QTextureImageDataPtr
+    \relates Qt3DRender::QTextureImageDataGenerator
+
+    Shared pointer to \l QTextureImageData.
+*/
+
+/*!
+    \fn QTextureImageDataPtr QTextureImageDataGenerator::operator()()
+
+    Implement the method to return the texture image data.
+*/
+
+/*!
+    \fn bool QTextureImageDataGenerator::operator ==(const QTextureImageDataGenerator &other) const
+
+    Implement the method to compare this texture data generator to \a other.
+    The operator is used to check if the \l QAbstractTextureImage needs to reload
+    the \l QTextureImageData.
+*/
+
 QAbstractTextureImagePrivate::QAbstractTextureImagePrivate()
     : QNodePrivate(),
       m_mipLevel(0),
@@ -90,6 +124,13 @@ QAbstractTextureImagePrivate::~QAbstractTextureImagePrivate()
  */
 
 /*!
+   \fn QTextureImageDataGeneratorPtr QAbstractTextureImage::dataGenerator() const
+
+    Implement this method to return the \l QTextureImageDataGeneratorPtr, which will
+    provide the data for the texture image.
+*/
+
+/*!
     Constructs a new QAbstractTextureImage instance with \a parent as parent.
  */
 QAbstractTextureImage::QAbstractTextureImage(QNode *parent)
diff --git a/src/render/texture/qtextureimage.cpp b/src/render/texture/qtextureimage.cpp
index dab92082a..dbe0ff05c 100644
--- a/src/render/texture/qtextureimage.cpp
+++ b/src/render/texture/qtextureimage.cpp
@@ -71,6 +71,59 @@ namespace Qt3DRender {
 */
 
 /*!
+    \enum QTextureImage::Status
+
+    This  enumeration specifies the status values for texture image loading.
+
+    \value None The texture image loading has not been started yet.
+    \value Loading The texture image loading has started, but not finised.
+    \value Ready The texture image loading has finished.
+    \value Error The texture image loading confronted an error.
+*/
+
+/*!
+    \qmlproperty url TextureImage::source
+
+    This property holds the source url from which data for the texture
+    image will be loaded.
+*/
+
+/*!
+    \qmlproperty enumeration TextureImage::status
+
+    This property holds the status of the texture image loading.
+
+    \list
+    \li TextureImage.None
+    \li TextureImage.Loading
+    \li TextureImage.Ready
+    \li TextureImage.Error
+    \endlist
+    \readonly
+*/
+
+/*!
+    \property QTextureImage::source
+
+    This property holds the source url from which data for the texture
+    image will be loaded.
+*/
+
+/*!
+    \property QTextureImage::status
+
+    This property holds the status of the texture image loading.
+
+    \list
+    \li TextureImage.None
+    \li TextureImage.Loading
+    \li TextureImage.Ready
+    \li TextureImage.Error
+    \endlist
+    \readonly
+*/
+
+/*!
     Constructs a new Qt3DRender::QTextureImage instance with \a parent as parent.
  */
 QTextureImage::QTextureImage(QNode *parent)
@@ -93,7 +146,7 @@ QUrl QTextureImage::source() const
 }
 
 /*!
- * \return the current status.
+    \return the current status.
  */
 QTextureImage::Status QTextureImage::status() const
 {
@@ -102,20 +155,6 @@ QTextureImage::Status QTextureImage::status() const
 }
 
 /*!
-  \property Qt3DRender::QTextureImage::source
-
-  This property holds the source url from which data for the texture
-  image will be loaded.
-*/
-
-/*!
-  \qmlproperty url Qt3D.Render::TextureImage::source
-
-  This property holds the source url from which data for the texture
-  image will be loaded.
-*/
-
-/*!
     Sets the source url of the texture image to \a source.
     \note This triggers a call to update()
  */
@@ -130,8 +169,8 @@ void QTextureImage::setSource(const QUrl &source)
 }
 
 /*!
- * Sets the status to \a status.
- * \param status
+    Sets the status to \a status.
+    \param status
  */
 void QTextureImage::setStatus(Status status)
 {
@@ -152,8 +191,8 @@ QTextureImageDataGeneratorPtr QTextureImage::dataGenerator() const
 }
 
 /*!
- * Sets the scene change event to \a change.
- * \param change
+    Sets the scene change event to \a change.
+    \param change
  */
 void QTextureImage::sceneChangeEvent(const Qt3DCore::QSceneChangePtr &change)
 {
@@ -164,8 +203,8 @@ void QTextureImage::sceneChangeEvent(const Qt3DCore::QSceneChangePtr &change)
 }
 
 /*!
- * The constructor creats a new QImageTextureDataFunctor::QImageTextureDataFunctor
- * instance with the specified \a url.
+    The constructor creates a new QImageTextureDataFunctor::QImageTextureDataFunctor
+    instance with the specified \a url.
  */
 QImageTextureDataFunctor::QImageTextureDataFunctor(const QUrl &url)
     : QTextureImageDataGenerator()