[Qt] Document QMapbox + qdoc fixes

4 files changed, 224 insertions, 20 deletions

diff --git a/platform/qt/config.qdocconf b/platform/qt/config.qdocconf
index 7dbe6423eb..b8ade81bb2 100644
--- a/platform/qt/config.qdocconf
+++ b/platform/qt/config.qdocconf
@@ -4,10 +4,13 @@ include($QT_INSTALL_DOCS/global/compat.qdocconf)
 include($QT_INSTALL_DOCS/global/fileextensions.qdocconf)
 include($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)
 
+Cpp.ignoretokens = Q_DECL_EXPORT
+
 project     = QMapboxGL
 description = Mapbox Qt SDK
 language    = Cpp
 
+outputdir   = docs
 headerdirs += include
 sourcedirs += src
 
diff --git a/platform/qt/include/qmapbox.hpp b/platform/qt/include/qmapbox.hpp
index e11214f473..f2d96412a9 100644
--- a/platform/qt/include/qmapbox.hpp
+++ b/platform/qt/include/qmapbox.hpp
@@ -11,23 +11,15 @@
 
 namespace QMapbox {
 
-// Reflects mbgl::Point<double>.
 typedef QPair<double, double> Coordinate;
 typedef QPair<Coordinate, double> CoordinateZoom;
-
-// Reflects mbgl::ProjectedMeters<double>.
 typedef QPair<double, double> ProjectedMeters;
 
-// Reflects mbgl::{LineString,LinearRing,MultiPoint}<double>.
 typedef QList<Coordinate> Coordinates;
-
-// Reflects mbgl::{MultiLineString,Polygon}<double>.
 typedef QList<Coordinates> CoordinatesCollection;
 
-// Reflects mbgl::MultiPolygon<double>.
 typedef QList<CoordinatesCollection> CoordinatesCollections;
 
-// Reflects mbgl::Feature.
 struct Q_DECL_EXPORT Feature {
     enum Type {
         PointType = 1,
@@ -40,7 +32,6 @@ struct Q_DECL_EXPORT Feature {
     QVariant id;
 };
 
-// Reflects mbgl::ShapeAnnotationGeometry.
 struct Q_DECL_EXPORT ShapeAnnotationGeometry {
     enum Type {
         LineStringType,
@@ -52,13 +43,11 @@ struct Q_DECL_EXPORT ShapeAnnotationGeometry {
     CoordinatesCollections geometry;
 };
 
-// Reflects mbgl::SymbolAnnotation.
 struct Q_DECL_EXPORT SymbolAnnotation {
     Coordinate geometry;
     QString icon;
 };
 
-// Reflects mbgl::LineAnnotation.
 struct Q_DECL_EXPORT LineAnnotation {
     ShapeAnnotationGeometry geometry;
     float opacity = 1.0f;
@@ -66,7 +55,6 @@ struct Q_DECL_EXPORT LineAnnotation {
     QColor color = Qt::black;
 };
 
-// Reflects mbgl::FillAnnotation.
 struct Q_DECL_EXPORT FillAnnotation {
     ShapeAnnotationGeometry geometry;
     float opacity = 1.0f;
@@ -74,19 +62,15 @@ struct Q_DECL_EXPORT FillAnnotation {
     QVariant outlineColor;
 };
 
-// Reflects mbgl::StyleSourcedAnnotation.
 struct Q_DECL_EXPORT StyleSourcedAnnotation {
     ShapeAnnotationGeometry geometry;
     QString layerID;
 };
 
-// SymbolAnnotation, LineAnnotation, FillAnnotation, StyleSourcedAnnotation.
 typedef QVariant Annotation;
-
 typedef quint32 AnnotationID;
 typedef QList<AnnotationID> AnnotationIDs;
 
-// Reflects mbgl::NetworkStatus::Status.
 enum NetworkMode {
     Online, // Default
     Offline,
diff --git a/platform/qt/src/qmapbox.cpp b/platform/qt/src/qmapbox.cpp
index 4e414c50a2..62bfde4fa8 100644
--- a/platform/qt/src/qmapbox.cpp
+++ b/platform/qt/src/qmapbox.cpp
@@ -24,17 +24,225 @@ static_assert(mbgl::underlying_type(QMapbox::Feature::PolygonType) == mbgl::unde
 
 namespace QMapbox {
 
+/*!
+    \namespace QMapbox
+    \inmodule Mapbox Qt SDK
+
+    Contains miscellaneous Mapbox bindings used throughout QMapboxGL.
+*/
+
+/*!
+    \typedef QMapbox::Coordinate
+
+    Alias for QPair<double, double>.
+    Representation for geographical coordinates - latitude and longitude, respectively.
+*/
+
+/*!
+    \typedef QMapbox::CoordinateZoom
+
+    Alias for QPair<Coordinate, double>.
+    Used as return value in QMapboxGL::coordinateZoomForBounds.
+*/
+
+/*!
+    \typedef QMapbox::ProjectedMeters
+
+    Alias for QPair<double, double>.
+    Representation for projected meters - northing and easting, respectively.
+*/
+
+/*!
+    \typedef QMapbox::Coordinates
+
+    Alias for QList<QMapbox::Coordinate>.
+    A list of QMapbox::Coordinate objects.
+*/
+
+/*!
+    \typedef QMapbox::CoordinatesCollection
+
+    Alias for QList<QMapbox::Coordinates>.
+    A list of QMapbox::Coordinates objects.
+*/
+
+/*!
+    \typedef QMapbox::CoordinatesCollections
+
+    Alias for QList<QMapbox::CoordinatesCollection>.
+    A list of QMapbox::CoordinatesCollection objects.
+*/
+
+/*!
+    \class QMapbox::Feature
+
+    \inmodule Mapbox Qt SDK
+
+    Represents \l {https://www.mapbox.com/help/define-features/}{map features}
+    via its \a type (PointType, LineStringType or PolygonType), \a geometry, \a
+    properties map and \a id (optional).
+*/
+
+/*!
+    \enum QMapbox::Feature::Type
+
+    This enum is used as basis for geometry disambiguation in QMapbox::Feature.
+
+    \value PointType      A point geometry type. Means a single or a collection of points.
+    \value LineStringType A line string geometry type. Means a single or a collection of line strings.
+    \value PolygonType    A polygon geometry type. Means a single or a collection of polygons.
+*/
+
+/*!
+    \class QMapbox::ShapeAnnotationGeometry
+
+    \inmodule Mapbox Qt SDK
+
+    Represents a shape annotation geometry.
+*/
+
+/*!
+    \enum QMapbox::ShapeAnnotationGeometry::Type
+
+    This enum is used as basis for shape annotation geometry disambiguation.
+
+    \value PolygonType         A polygon geometry type.
+    \value LineStringType      A line string geometry type.
+    \value MultiPolygonType    A polygon geometry collection type.
+    \value MultiLineStringType A line string geometry collection type.
+*/
+
+/*!
+    \class QMapbox::SymbolAnnotation
+
+    \inmodule Mapbox Qt SDK
+
+    A symbol annotation comprises of its geometry and an icon identifier.
+*/
+
+/*!
+    \class QMapbox::LineAnnotation
+
+    \inmodule Mapbox Qt SDK
+
+    Represents a line annotation object, along with its properties.
+
+    A line annotation comprises of its geometry and line properties such as opacity, width and color.
+*/
+
+/*!
+    \class QMapbox::FillAnnotation
+
+    \inmodule Mapbox Qt SDK
+
+    Represents a fill annotation object, along with its properties.
+
+    A fill annotation comprises of its geometry and fill properties such as opacity, color and outline color.
+*/
+
+/*!
+    \class QMapbox::StyleSourcedAnnotation
+
+    \inmodule Mapbox Qt SDK
+
+    Represents a style sourced annotation object, along with its properties.
+
+    A style sourced annotation comprises of its geometry and a layer identifier.
+*/
+
+/*!
+    \typedef QMapbox::Annotation
+
+    Alias for QVariant.
+    Container that encapsulates either a symbol, a line, a fill or a style sourced annotation.
+*/
+
+/*!
+    \typedef QMapbox::AnnotationID
+
+    Alias for quint32 representing an annotation identifier.
+*/
+
+/*!
+    \typedef QMapbox::AnnotationIDs
+
+    Alias for QList<quint32> representing a container of annotation identifiers.
+*/
+
+/*!
+    \typedef QMapbox::CustomLayerDeinitializeFunction
+
+    Represents a callback to be called when destroying a custom layer.
+
+    \warning This is used for delegating the rendering of a layer to the user of
+    this API and is not officially supported. Use at your own risk.
+*/
+
+/*!
+    \typedef QMapbox::CustomLayerInitializeFunction
+
+    Represents a callback to be called when initializing a custom layer.
+
+    \warning This is used for delegating the rendering of a layer to the user of
+    this API and is not officially supported. Use at your own risk.
+*/
+
+/*!
+    \typedef QMapbox::CustomLayerRenderFunction
+
+    Represents a callback to be called on each render pass for a custom layer.
+
+    \warning This is used for delegating the rendering of a layer to the user of
+    this API and is not officially supported. Use at your own risk.
+*/
+
+/*!
+    \enum QMapbox::NetworkMode
+
+    This enum represents whether server requests can be performed via network.
+
+    \value Online  Server network requests are accessible.
+    \value Offline Only requests to the local cache are accessible.
+*/
+
+/*!
+    \class QMapbox::CustomLayerRenderParameters
+    \inmodule Mapbox Qt SDK
+
+    QMapbox::CustomLayerRenderParameters provides the data passed on each render
+    pass for a custom layer.
+*/
+
+/*!
+    \fn QMapbox::NetworkMode QMapbox::networkMode()
+
+    Returns the current QMapbox::NetworkMode.
+*/
 Q_DECL_EXPORT NetworkMode networkMode()
 {
     return static_cast<NetworkMode>(mbgl::NetworkStatus::Get());
 }
 
+/*!
+    \fn void QMapbox::setNetworkMode(QMapbox::NetworkMode mode)
+
+    Forwards the network status \a mode to Mapbox GL Native engine.
+
+    File source requests uses the available network when \a mode is set to \a
+    Online, otherwise scoped to the local cache.
+*/
 Q_DECL_EXPORT void setNetworkMode(NetworkMode mode)
 {
     mbgl::NetworkStatus::Set(static_cast<mbgl::NetworkStatus::Status>(mode));
 }
 
-Q_DECL_EXPORT QList<QPair<QString, QString>>& defaultStyles()
+/*!
+    \fn QList<QPair<QString, QString> >& QMapbox::defaultStyles()
+
+    Returns a list containing a pair of string objects, representing the style
+    URL and name, respectively.
+*/
+Q_DECL_EXPORT QList<QPair<QString, QString> >& defaultStyles()
 {
     static QList<QPair<QString, QString>> styles;
 
@@ -48,6 +256,15 @@ Q_DECL_EXPORT QList<QPair<QString, QString>>& defaultStyles()
     return styles;
 }
 
+/*!
+    \fn void QMapbox::initializeGLExtensions()
+
+    Initializes the OpenGL extensions such as Vertex Array Objects (VAOs),
+    required by Mapbox GL Native engine.
+
+    Should be called only once, after an OpenGL context is available.
+    Consecutive calls are ignored.
+*/
 Q_DECL_EXPORT void initializeGLExtensions()
 {
     mbgl::gl::InitializeExtensions([](const char* name) {
@@ -61,4 +278,4 @@ Q_DECL_EXPORT void initializeGLExtensions()
     });
 }
 
-}
+} // namespace QMapbox
diff --git a/platform/qt/src/qmapboxgl.cpp b/platform/qt/src/qmapboxgl.cpp
index 1c7d88bb9a..9b6459f1e3 100644
--- a/platform/qt/src/qmapboxgl.cpp
+++ b/platform/qt/src/qmapboxgl.cpp
@@ -1127,7 +1127,7 @@ double QMapboxGL::metersPerPixelAtLatitude(double latitude, double zoom) const
 }
 
 /*!
-    Return the projected meters for a given \a coordinate object.
+    Return the projected meters for a given \a coordinate_ object.
 */
 QMapbox::ProjectedMeters QMapboxGL::projectedMetersForCoordinate(const QMapbox::Coordinate &coordinate_) const
 {
@@ -1271,7 +1271,7 @@ void QMapboxGL::addSource(const QString &id, const QVariantMap &params)
 }
 
 /*!
-    Returns true if the layer with given \a id exists, false otherwise.
+    Returns true if the layer with given \a sourceID exists, false otherwise.
 */
 bool QMapboxGL::sourceExists(const QString& sourceID)
 {