Doc: Review doc Qt3D

Task-number: QTBUG-44180
Change-Id: Ia5ce031397f9b03c5ba692aa30b6097dc60e59e3
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

9 files changed, 63 insertions, 33 deletions

diff --git a/src/core/aspects/qabstractaspect.cpp b/src/core/aspects/qabstractaspect.cpp
index 05842ffa5..1de4069e4 100644
--- a/src/core/aspects/qabstractaspect.cpp
+++ b/src/core/aspects/qabstractaspect.cpp
@@ -70,7 +70,7 @@ QAbstractAspectPrivate *QAbstractAspectPrivate::get(QAbstractAspect *aspect)
 /*!
     \class Qt3D::QAbstractAspect
     \inmodule Qt3DCore
-    \brief QAbstractAspect is the base class for aspects that provide a vertical slice of behavior
+    \brief QAbstractAspect is the base class for aspects that provide a vertical slice of behavior.
 */
 QAbstractAspect::QAbstractAspect(AspectType aspectType, QObject *parent)
     : QObject(*new QAbstractAspectPrivate(this), parent)
diff --git a/src/core/doc/src/qt3dcore-index.qdoc b/src/core/doc/src/qt3dcore-index.qdoc
index 5e9e45d14..4fc04112d 100644
--- a/src/core/doc/src/qt3dcore-index.qdoc
+++ b/src/core/doc/src/qt3dcore-index.qdoc
@@ -35,12 +35,29 @@
 ****************************************************************************/
 
 /*!
-    \page qt3dcore-index.html
-    \title Qt3D Core
+    \title  Qt3D Core
+    \page   qt3dcore-index.html
+    \brief  The Qt3D Core module contains functionality to support near-realtime simulation systems.
 
-    \brief The Qt3D Core module contains functionality to support near-realtime simulation systems.
 
     \section1 Getting Started
 
+    To use Qt3D classes, add this directive into the C++ files:
+
+    \code
+       #include <Qt3DCore>
+    \endcode
+
+    To link against the corresponding C++ libraries, add the following to your qmake project file:
+
+    \code
+       QT += 3dcore
+    \endcode
+
+    \section1 Reference
+
+    \list
+       \li \l {Qt3D Core C++ Classes}
+    \endlist
 
 */
diff --git a/src/core/doc/src/qt3dcore-module.qdoc b/src/core/doc/src/qt3dcore-module.qdoc
index 8ff5473b3..20cef4e80 100644
--- a/src/core/doc/src/qt3dcore-module.qdoc
+++ b/src/core/doc/src/qt3dcore-module.qdoc
@@ -36,7 +36,7 @@
 
 /*!
     \module Qt3DCore
-    \title Qt3D Core
+    \title Qt3D Core C++ Classes
     \brief The Qt3D Core module contains functionality to support near-realtime simulation systems.
 
     \ingroup modules
diff --git a/src/core/qchangearbiter.cpp b/src/core/qchangearbiter.cpp
index c42223a20..7c7dafd0f 100644
--- a/src/core/qchangearbiter.cpp
+++ b/src/core/qchangearbiter.cpp
@@ -56,14 +56,14 @@ namespace Qt3D {
     \inmodule Qt3DCore
     \since 5.5
 
-    \brief Act as a messages router between observables and observers.
+    \brief Acts as a message router between observables and observers.
 
     Observables can be of two types: QNode observables and QObservableInterfaces.
     QNode notifications are sent from the frontend QNode and delivered to the backend observers.
     QObservableInterface notifications are sent from backend nodes to backend observers and/or to the
     registered QPostman, which in turn delivers the notifications to the target frontend QNode.
 
-    QNode observables are registered automatically. However QObservableInterface object have to be registered manually
+    QNode observables are registered automatically. However, QObservableInterface object have to be registered manually
     by providing the QNodeId of the corresponding frontend QNode.
 
     Observers can be registered to receive messages from a QObservableInterface/QNode observable by providing a QNode NodeUuid.
diff --git a/src/core/resources/qcircularbuffer.qdoc b/src/core/resources/qcircularbuffer.qdoc
index ac3d07535..02b5bba27 100644
--- a/src/core/resources/qcircularbuffer.qdoc
+++ b/src/core/resources/qcircularbuffer.qdoc
@@ -127,7 +127,7 @@
     If you wish to pass a C++ array to a function and that function is expensive to call,
     then you may wish to use the data() method so that you only need to call your
     expensive function once. If your function is cheap and you have a large circular
-    buffer (so that linearizing it is expensive) then you may wish to use dataOne() and
+    buffer (so that linearizing it is expensive), then you may wish to use dataOne() and
     dataTwo() and call your function twice.
 
     Here is a simple example that shows the semantics of how QCircularBuffer operates:
@@ -153,10 +153,10 @@
     remove() functions can be slow (\l{linear time}) for large circular buffers,
     because they require moving many items in the circular buffer by one or more positions
     in memory. The implementation does however take care to minimize the number of
-    items that need to be moved. In the extreme worst case for insert() and remove()
+    items that need to be moved. In the extreme worst case for insert() and remove(),
     half of the items will be moved in memory. QCircularBuffer also takes care
     to move items around using the best method available for the type being stored.
-    If your type is movable then it is best to tell Qt about this by using the
+    If your type is movable, then it is best to tell Qt about this by using the
     Q_DECLARE_TYPEINFO() macro. In such cases memory moves are performed using
     memmove() rather than calling the copy constructor for each item. If you want
     a container class that always provides fast insertion/removal in the middle,
@@ -184,18 +184,16 @@
     support \c operator==().  These requirements are documented on a
     per-function basis.
 
-    Like the other container classes, QCircularBuffer provides \l{Java-style
-    iterators} (QCircularBufferIterator and QMutableCircularBufferIterator) and
-    \l{STL-style iterators} (Qt3D::QCircularBuffer::const_iterator and
-    Qt3D::QCircularBuffer::iterator). In practice, these are rarely used, because
-    you can use indexes into the QCircularBuffer.
+    QCircularBuffer provides \l{STL-Style Iterators} (\l {Qt3D::QCircularBuffer::}{const_iterator)
+    and \l {Qt3D::QCircularBuffer::}{iterator}). In practice, these are rarely used,
+    because you can use indexes into the QCircularBuffer.
 
-    QCircularBuffer does \e not support inserting, prepending, appending or replacing
-    with references to its own values. Doing so will cause your application to
-    abort with an error message.
+    QCircularBuffer does \e not support inserting, prepending, appending, or
+    replacing with references to its own values. Doing so will cause your
+    application to abort with an error message.
 
     \sa Qt3D::QCircularBuffer::iterator, Qt3D::QCircularBuffer::const_iterator,
-    QCircularBufferIterator, QMutableCircularBufferIterator, QVector, QList, QLinkedList
+    QVector, QList, QLinkedList
 */
 
 /*! \fn Qt3D::QCircularBuffer::QCircularBuffer()
@@ -258,7 +256,7 @@
 
 /*! \fn Qt3D::QCircularBuffer::iterator Qt3D::QCircularBuffer::begin()
 
-    Returns an \l{STL-style iterator} pointing to the first item in
+    Returns an \l{STL-Style iterators}{STL-style iterator} pointing to the first item in
     the circular buffer.
 
     \sa constBegin(), end()
@@ -271,7 +269,7 @@
 
 /*! \fn Qt3D::QCircularBuffer::const_iterator Qt3D::QCircularBuffer::constBegin() const
 
-    Returns a const \l{STL-style iterator} pointing to the first item in
+    Returns a const \l{STL-Style Iterators}{STL-style iterator} pointing to the first item in
     the circular buffer.
 
     \sa begin(), constEnd()
@@ -279,7 +277,7 @@
 
 /*! \fn Qt3D::QCircularBuffer::iterator Qt3D::QCircularBuffer::end()
 
-    Returns an \l{STL-style iterator} pointing to the imaginary item
+    Returns an \l {STL-Style Iterators} {STL-style iterator} pointing to the imaginary item
     after the last item in the circular buffer.
 
     \sa begin(), constEnd()
@@ -292,7 +290,7 @@
 
 /*! \fn Qt3D::QCircularBuffer::const_iterator Qt3D::QCircularBuffer::constEnd() const
 
-    Returns a const \l{STL-style iterator} pointing to the imaginary item
+    Returns a const \l{STL-Style Iterators} {STL-style iterator} pointing to the imaginary item
     after the last item in the circular buffer.
 
     \sa constBegin(), end()
@@ -1189,11 +1187,11 @@
     \inmodule Qt3DCore
     \brief The Qt3D::QCircularBuffer::iterator class provides an STL-style non-const iterator for QCircularBuffer.
 
-    QCircularBuffer provides both \l{STL-style iterators} and \l{Java-style
-    iterators}.
+    QCircularBuffer provides both \l{STL-Style Iterators} and \l{Java-Style
+    Iterators}.
 
     \sa Qt3D::QCircularBuffer::begin(), Qt3D::QCircularBuffer::end(),
-    Qt3D::QCircularBuffer::const_iterator, QMutableCircularBufferIterator
+    Qt3D::QCircularBuffer::const_iterator
 */
 
 /*! \typedef Qt3D::QCircularBuffer::iterator::iterator_category
@@ -1393,11 +1391,11 @@
     \inmodule Qt3DCore
     \brief The Qt3D::QCircularBuffer::const_iterator class provides an STL-style const iterator for QCircularBuffer.
 
-    QCircularBuffer provides both \l{STL-style iterators} and \l{Java-style
-    iterators}.
+    QCircularBuffer provides both \l{STL-Style Iterators} and \l{Java-Style
+    Iterators}.
 
     \sa Qt3D::QCircularBuffer::constBegin(), Qt3D::QCircularBuffer::constEnd(),
-    Qt3D::QCircularBuffer::iterator, QCircularBufferIterator
+    Qt3D::QCircularBuffer::iterator
 */
 
 /*! \typedef Qt3D::QCircularBuffer::const_iterator::iterator_category
diff --git a/src/core/resources/qframeallocator.cpp b/src/core/resources/qframeallocator.cpp
index 48f0e5bbc..5b8c9aaf5 100644
--- a/src/core/resources/qframeallocator.cpp
+++ b/src/core/resources/qframeallocator.cpp
@@ -37,7 +37,7 @@
 /*!
     \class Qt3D::QFrameAllocator
     \inmodule Qt3DCore
-    \brief Provides a pool of memory chuncks to be used to allocate objects on a per frame basis.
+    \brief Provides a pool of memory chunks to be used to allocate objects on a per frame basis.
 
     The memory can be recycled by following frames by calling clear which won't deallocate any memory.
 */
@@ -193,7 +193,7 @@ void QFixedFrameAllocator::release()
     m_lastFreedChunck = Q_NULLPTR;
 }
 
-// Allows to reuse chuncks without having to reinitialize and reallocate them
+// Allows to reuse chunks without having to reinitialize and reallocate them
 void QFixedFrameAllocator::clear()
 {
     for (int i = m_chunks.size() - 1; i >= 0; i--)
diff --git a/src/core/resources/qresourcemanager.cpp b/src/core/resources/qresourcemanager.cpp
index ed6cf4601..05a1592d9 100644
--- a/src/core/resources/qresourcemanager.cpp
+++ b/src/core/resources/qresourcemanager.cpp
@@ -90,7 +90,7 @@
     \inmodule Qt3DCore
     \since 5.5
 
-    \brief Provided locking access to a resource through the use of a QReadWriteLock.
+    \brief Provides locking access to a resource through the use of a QReadWriteLock.
 
     This policy should be used in a QResourceManager when multiple threads may access the manager for
     read and write operations at the same time.
diff --git a/src/render/doc/src/qt3drender-index.qdoc b/src/render/doc/src/qt3drender-index.qdoc
index 620b39975..a29238f95 100644
--- a/src/render/doc/src/qt3drender-index.qdoc
+++ b/src/render/doc/src/qt3drender-index.qdoc
@@ -42,5 +42,20 @@
 
     \section1 Getting Started
 
+    To use Qt3D classes, add this directive into the C++ files:
 
+    \code
+       #include <Qt3DRenderer>
+    \endcode
+
+    To link against the corresponding C++ libraries, add the following to your qmake project file:
+
+    \code
+       QT += 3drenderer
+    \endcode
+
+    \section1 Reference
+    \list
+    \li \l {Qt3D Render C++ Classes}
+    \endlist
 */
diff --git a/src/render/doc/src/qt3drender-module.qdoc b/src/render/doc/src/qt3drender-module.qdoc
index a3bb44e6c..dd2f22a3b 100644
--- a/src/render/doc/src/qt3drender-module.qdoc
+++ b/src/render/doc/src/qt3drender-module.qdoc
@@ -36,7 +36,7 @@
 
 /*!
     \module Qt3DRender
-    \title Qt3D Render
+    \title Qt3D Render C++ Classes
     \brief The Qt3D Render module contains functionality to support 2D and 3D rendering using Qt3D.
 
     \ingroup modules