[Qt] Add more docs

2 files changed, 457 insertions, 78 deletions

diff --git a/platform/qt/include/qmapboxgl.hpp b/platform/qt/include/qmapboxgl.hpp
index 1a050540a1..086601af25 100644
--- a/platform/qt/include/qmapboxgl.hpp
+++ b/platform/qt/include/qmapboxgl.hpp
@@ -181,6 +181,8 @@ public:
 
     void setTransitionOptions(qint64 duration, qint64 delay = 0);
 
+    void addAnnotationIcon(const QString &name, const QImage &sprite);
+
     QMapbox::AnnotationID addPointAnnotation(const QMapbox::PointAnnotation &);
     QMapbox::AnnotationID addShapeAnnotation(const QMapbox::ShapeAnnotation &);
 
@@ -199,8 +201,6 @@ public:
 
     void resize(const QSize &size, const QSize &framebufferSize);
 
-    void addAnnotationIcon(const QString &name, const QImage &sprite);
-
     QPointF pixelForCoordinate(const QMapbox::Coordinate &) const;
     QMapbox::Coordinate coordinateForPixel(const QPointF &) const;
 
diff --git a/platform/qt/src/qmapboxgl.cpp b/platform/qt/src/qmapboxgl.cpp
index d9f8d48b2f..86604a945f 100644
--- a/platform/qt/src/qmapboxgl.cpp
+++ b/platform/qt/src/qmapboxgl.cpp
@@ -141,14 +141,14 @@ std::unique_ptr<const mbgl::SpriteImage> toSpriteImage(const QImage &sprite) {
 /*!
     \enum QMapboxGLSettings::GLContextMode
 
-    This enum sets the expectations for the GL state.
+    This enum sets the expectations for the OpenGL state.
 
-    \value UniqueGLContext  The GL context is only used by QMapboxGL, so it is not
+    \value UniqueGLContext  The OpenGL context is only used by QMapboxGL, so it is not
     reset before each rendering. Use this mode if the intention is to only draw a
     fullscreen map.
 
-    \value SharedGLContext  The GL context is shared and the state will be restored
-    before rendering. This mode is safer when GL calls are performed prior of after
+    \value SharedGLContext  The OpenGL context is shared and the state will be restored
+    before rendering. This mode is safer when OpenGL calls are performed prior of after
     we call QMapboxGL::render for rendering a map.
 
     \sa contextMode()
@@ -202,7 +202,7 @@ QMapboxGLSettings::QMapboxGLSettings()
 
 /*!
     Returns the OpenGL context mode. This is specially important when mixing
-    with other GL draw calls.
+    with other OpenGL draw calls.
 
     By default, it is set to QMapboxGLSettings::SharedGLContext.
 */
@@ -285,7 +285,7 @@ void QMapboxGLSettings::setCacheDatabaseMaximumSize(unsigned size)
     \l {https://github.com/mapbox/mapbox-gl-native/blob/master/bin/offline.sh}
     {Offline Tool}.
 
-    By default, it is set to \b :memory: meaning it will create an in-memory
+    By default, it is set to \c :memory: meaning it will create an in-memory
     cache instead of a file on disk.
 */
 QString QMapboxGLSettings::cacheDatabasePath() const
@@ -296,7 +296,7 @@ QString QMapboxGLSettings::cacheDatabasePath() const
 /*!
     Sets the cache database \a path.
 
-    Setting the \a path to \b :memory: will create an in-memory cache.
+    Setting the \a path to \c :memory: will create an in-memory cache.
 */
 void QMapboxGLSettings::setCacheDatabasePath(const QString &path)
 {
@@ -305,7 +305,7 @@ void QMapboxGLSettings::setCacheDatabasePath(const QString &path)
 
 /*!
     Returns the asset path, which is the root directory from where
-    the \b asset:// scheme gets resolved in a style. \b asset:// can be used
+    the \c asset:// scheme gets resolved in a style. \c asset:// can be used
     for loading a resource from the disk in a style rather than fetching
     it from the network.
 
@@ -327,7 +327,7 @@ void QMapboxGLSettings::setAssetPath(const QString &path)
 /*!
     Returns the access token.
 
-    By default, it is taken from the environment variable \b MAPBOX_ACCESS_TOKEN
+    By default, it is taken from the environment variable \c MAPBOX_ACCESS_TOKEN
     or empty if the variable is not set.
 */
 QString QMapboxGLSettings::accessToken() const {
@@ -381,12 +381,62 @@ void QMapboxGLSettings::setApiBaseUrl(const QString& url)
     QNetworkAccessManager for HTTP requests and QString for UTF-8 manipulation.
 
     QMapboxGL is not thread-safe and it is assumed that it will be accessed from
-    the same thread as the thread where the GL context lives.
+    the same thread as the thread where the OpenGL context lives.
 
     \since 4.7
 */
 
 /*!
+    \enum QMapboxGL::MapChange
+
+    This enum represents the last changed occurred to the map state.
+
+    \value MapChangeRegionWillChange                      A region of the map will change, like
+    when resizing the map.
+
+    \value MapChangeRegionWillChangeAnimated              Not in use by QMapboxGL.
+
+    \value MapChangeRegionIsChanging                      A region of the map is changing.
+
+    \value MapChangeRegionDidChange                       A region of the map finished changing.
+
+    \value MapChangeRegionDidChangeAnimated               Not in use by QMapboxGL.
+
+    \value MapChangeWillStartLoadingMap                   The map is getting loaded. This state
+    is set only once right after QMapboxGL is created and a style is set.
+
+    \value MapChangeDidFinishLoadingMap                   All the resources were loaded and parsed
+    and the map is fully rendered. After this state the mapChanged() signal won't fire again unless
+    the is some client side interaction with the map or a tile expires, causing a new resource
+    to be requested from the network.
+
+    \value MapChangeDidFailLoadingMap                     An error occurred when loading the map.
+
+    \value MapChangeWillStartRenderingFrame               Just before rendering the frame. This
+    is the state of the map just after calling render() and might happened many times before
+    the map is fully loaded.
+
+    \value MapChangeDidFinishRenderingFrame               The current frame was rendered but was
+    left in a partial state. Some parts of the map might be missing because have not arrived
+    from the network or are being parsed.
+
+    \value MapChangeDidFinishRenderingFrameFullyRendered  The current frame was fully rendered.
+
+    \value MapChangeWillStartRenderingMap                 Set once when the map is about to get
+    rendered for the first time.
+
+    \value MapChangeDidFinishRenderingMap                 Not in use by QMapboxGL.
+
+    \value MapChangeDidFinishRenderingMapFullyRendered    Map is fully loaded and rendered.
+
+    \value MapChangeDidFinishLoadingStyle                 The style was loaded.
+
+    \value MapChangeSourceDidChange                       A source has changed.
+
+    \sa mapChanged()
+*/
+
+/*!
     \enum QMapboxGL::NorthOrientation
 
     This enum sets the orientation of the north bearing. It will directly affect bearing when
@@ -445,7 +495,7 @@ void QMapboxGL::cycleDebugOptions()
 
     Sets a new \a style from a JSON that must conform to the
     \l {https://www.mapbox.com/mapbox-gl-style-spec/}
-    {Mapbox Style Specification}.
+    {Mapbox style specification}.
 
     \note In case of a invalid style it will trigger a mapChanged
     signal with QMapboxGL::MapChangeDidFailLoadingMap as argument.
@@ -506,8 +556,9 @@ void QMapboxGL::setLatitude(double latitude_)
     \property QMapboxGL::longitude
     \brief the map current longitude in degrees.
 
-    Setting a longitude doesn't necessarily mean it will be accepted since QMapboxGL
-    might constrain it within the limits of the Web Mercator projection.
+    Setting a longitude beyond the limits of the Web Mercator projection will make
+    the map wrap. As an example, setting the longitude to 360 is effectively the same
+    as setting it to 0.
 */
 double QMapboxGL::longitude() const
 {
@@ -524,8 +575,11 @@ void QMapboxGL::setLongitude(double longitude_)
     \brief the map scale factor.
 
     This property is used to zoom the map. When \a center is defined, the map will
-    scale in the direction of the center pixel coordinates. This function could be used for
-    implementing a pinch gesture or zooming by using the mouse scroll wheel.
+    scale in the direction of the center pixel coordinates. The \a center will remain
+    at the same pixel coordinate after scaling as before calling this method.
+
+    \note This function could be used for implementing a pinch gesture or zooming
+    by using the mouse scroll wheel.
 
     \sa zoom()
 */
@@ -559,11 +613,21 @@ void QMapboxGL::setZoom(double zoom_)
     d_ptr->mapObj->setZoom(zoom_, d_ptr->margins);
 }
 
+/*!
+    Returns the minimum zoom level allowed for the map.
+
+    \sa maximumZoom()
+*/
 double QMapboxGL::minimumZoom() const
 {
     return d_ptr->mapObj->getMinZoom();
 }
 
+/*!
+    Returns the maximum zoom level allowed for the map.
+
+    \sa minimumZoom()
+*/
 double QMapboxGL::maximumZoom() const
 {
     return d_ptr->mapObj->getMaxZoom();
@@ -583,12 +647,14 @@ Coordinate QMapboxGL::coordinate() const
     return Coordinate(latLng.latitude, latLng.longitude);
 }
 
-void QMapboxGL::setCoordinate(const Coordinate &coordinate_)
+void QMapboxGL::setCoordinate(const QMapbox::Coordinate &coordinate_)
 {
     d_ptr->mapObj->setLatLng(mbgl::LatLng { coordinate_.first, coordinate_.second }, d_ptr->margins);
 }
 
 /*!
+    \fn QMapboxGL::setCoordinateZoom(const QMapbox::Coordinate &coordinate, double zoom)
+
     Convenience method for setting the \a coordinate and \a zoom simultaneously.
 
     \note Setting \a coordinate and \a zoom at once is more efficient than doing
@@ -597,7 +663,7 @@ void QMapboxGL::setCoordinate(const Coordinate &coordinate_)
     \sa zoom()
     \sa coordinate()
 */
-void QMapboxGL::setCoordinateZoom(const Coordinate &coordinate_, double zoom_)
+void QMapboxGL::setCoordinateZoom(const QMapbox::Coordinate &coordinate_, double zoom_)
 {
     d_ptr->mapObj->setLatLngZoom(
             mbgl::LatLng { coordinate_.first, coordinate_.second }, zoom_, d_ptr->margins);
@@ -678,27 +744,38 @@ void QMapboxGL::setPitch(double pitch_)
     d_ptr->mapObj->setPitch(pitch_);
 }
 
+/*!
+    Returns the north orientation mode.
+*/
 QMapboxGL::NorthOrientation QMapboxGL::northOrientation() const
 {
     return static_cast<QMapboxGL::NorthOrientation>(d_ptr->mapObj->getNorthOrientation());
 }
 
+/*!
+    Sets the north orientation mode to \a orientation.
+*/
 void QMapboxGL::setNorthOrientation(NorthOrientation orientation)
 {
     d_ptr->mapObj->setNorthOrientation(static_cast<mbgl::NorthOrientation>(orientation));
 }
 
-void QMapboxGL::setGestureInProgress(bool inProgress)
+/*!
+    Tells the map rendering engine that there is currently a gesture in \a progress. This
+    affects how the map renders labels, as it will use different texture filters if a gesture
+    is ongoing.
+*/
+void QMapboxGL::setGestureInProgress(bool progress)
 {
-    d_ptr->mapObj->setGestureInProgress(inProgress);
+    d_ptr->mapObj->setGestureInProgress(progress);
 }
 
 /*!
     Adds an \a className to the list of active classes. Layers tagged with a certain class
     will only be active when the class is added.
 
-    This was removed from \l {https://www.mapbox.com/mapbox-gl-style-spec/#layer-paint.*}
-    {the vector tiles specification} and should no longer be used.
+    This was removed from the \l {https://www.mapbox.com/mapbox-gl-style-spec/#layer-paint.*}
+    {Mapbox style specification} and should no longer be used.
 
     \deprecated
     \sa removeClass()
@@ -756,6 +833,13 @@ QStringList QMapboxGL::getClasses() const
     return classNames;
 }
 
+/*!
+    Sets the \a duration and \a delay of style class transitions. Style property
+    values transition to new values with animation when a new class is set.
+
+    \deprecated
+    \sa addClass()
+*/
 void QMapboxGL::setTransitionOptions(qint64 duration, qint64 delay) {
     static auto convert = [](qint64 value) -> mbgl::optional<mbgl::Duration> {
         return std::chrono::duration_cast<mbgl::Duration>(mbgl::Milliseconds(value));
@@ -770,77 +854,206 @@ mbgl::Annotation fromPointAnnotation(const PointAnnotation &pointAnnotation) {
     return mbgl::SymbolAnnotation { mbgl::Point<double> { coordinate.second, coordinate.first }, icon.toStdString() };
 }
 
-AnnotationID QMapboxGL::addPointAnnotation(const PointAnnotation &pointAnnotation)
+/*!
+    Adds a \a point annotation to the map.
+
+    Returns the unique identifier for the new annotation.
+
+    \sa addAnnotationIcon()
+*/
+QMapbox::AnnotationID QMapboxGL::addPointAnnotation(const QMapbox::PointAnnotation &point)
 {
-    return d_ptr->mapObj->addAnnotation(fromPointAnnotation(pointAnnotation));
+    return d_ptr->mapObj->addAnnotation(fromPointAnnotation(point));
 }
 
-void QMapboxGL::updatePointAnnotation(AnnotationID id, const PointAnnotation &pointAnnotation)
+/*!
+    Updates an existing \a point annotation referred by \a id.
+
+    \sa addAnnotationIcon()
+*/
+void QMapboxGL::updatePointAnnotation(QMapbox::AnnotationID id, const QMapbox::PointAnnotation &point)
 {
-    d_ptr->mapObj->updateAnnotation(id, fromPointAnnotation(pointAnnotation));
+    d_ptr->mapObj->updateAnnotation(id, fromPointAnnotation(point));
 }
 
-AnnotationID QMapboxGL::addShapeAnnotation(const ShapeAnnotation &shapeAnnotation)
+/*!
+    Adds a \a shape annotation to the map.
+
+    Returns the unique identifier for the new annotation.
+*/
+QMapbox::AnnotationID QMapboxGL::addShapeAnnotation(const QMapbox::ShapeAnnotation &shape)
 {
-    return d_ptr->mapObj->addAnnotation(fromQMapboxGLShapeAnnotation(shapeAnnotation));
+    return d_ptr->mapObj->addAnnotation(fromQMapboxGLShapeAnnotation(shape));
 }
 
-void QMapboxGL::removeAnnotation(AnnotationID annotationID)
+/*!
+    Removes an existing annotation referred by \a id.
+*/
+void QMapboxGL::removeAnnotation(QMapbox::AnnotationID id)
 {
-    d_ptr->mapObj->removeAnnotation(annotationID);
+    d_ptr->mapObj->removeAnnotation(id);
 }
 
-void QMapboxGL::setLayoutProperty(const QString& layer_, const QString& property, const QVariant& value)
+/*!
+    Sets a layout \a property \a value to an existing \a layer. The \a property string can be any
+    as defined by the \l {https://www.mapbox.com/mapbox-gl-style-spec/} {Mapbox style specification}
+    for layout properties.
+
+    This example hides the layer \c route:
+
+    \code
+        map->setLayoutProperty("route", "visibility", "none");
+    \endcode
+
+    This table describes the mapping between \l {https://www.mapbox.com/mapbox-gl-style-spec/#types}
+    {style types} and Qt types accepted by setLayoutProperty():
+
+    \table
+    \header
+        \li Mapbox style type
+        \li Qt type
+    \row
+        \li Enum
+        \li QString
+    \row
+        \li String
+        \li QString
+    \row
+        \li Boolean
+        \li \c bool
+    \row
+        \li Number
+        \li \c int, \c double or \c float
+    \row
+        \li Array
+        \li QVariantList
+    \endtable
+*/
+void QMapboxGL::setLayoutProperty(const QString& layer, const QString& property, const QVariant& value)
 {
     using namespace mbgl::style;
 
-    Layer* layer = d_ptr->mapObj->getLayer(layer_.toStdString());
-    if (!layer) {
-        qWarning() << "Layer not found:" << layer_;
+    Layer* layer_ = d_ptr->mapObj->getLayer(layer.toStdString());
+    if (!layer_) {
+        qWarning() << "Layer not found:" << layer;
         return;
     }
 
-    if (conversion::setLayoutProperty(*layer, property.toStdString(), value)) {
-        qWarning() << "Error setting layout property:" << layer_ << "-" << property;
+    if (conversion::setLayoutProperty(*layer_, property.toStdString(), value)) {
+        qWarning() << "Error setting layout property:" << layer << "-" << property;
         return;
     }
 }
 
-void QMapboxGL::setPaintProperty(const QString& layer_, const QString& property, const QVariant& value, const QString& klass_)
+/*!
+    Sets a paint \a property \a value to an existing \a layer. The \a property string can be any
+    as defined by the \l {https://www.mapbox.com/mapbox-gl-style-spec/} {Mapbox style specification}
+    for paint properties.
+
+    The argument \a styleClass is deprecated and is used for defining the style class for the paint
+    property.
+
+    For paint properties that take a color as \a value, such as \c fill-color, a string such as
+    \c blue can be passed or a QColor.
+
+    \code
+        map->setPaintProperty("route", "line-color", QColor("blue"));
+    \endcode
+
+    This table describes the mapping between \l {https://www.mapbox.com/mapbox-gl-style-spec/#types}
+    {style types} and Qt types accepted by setPaintProperty():
+
+    \table
+    \header
+        \li Mapbox style type
+        \li Qt type
+    \row
+        \li Color
+        \li QString or QColor
+    \row
+        \li Enum
+        \li QString
+    \row
+        \li String
+        \li QString
+    \row
+        \li Boolean
+        \li \c bool
+    \row
+        \li Number
+        \li \c int, \c double or \c float
+    \row
+        \li Array
+        \li QVariantList
+    \endtable
+
+    If the style specification defines the property's type as \b Array, use a QVariantList. For
+    example, the following code sets a \c route layer's \c line-dasharray property:
+
+    \code
+        QVariantList lineDashArray;
+        lineDashArray.append(1);
+        lineDashArray.append(2);
+
+        map->setPaintProperty("route","line-dasharray", lineDashArray);
+    \endcode
+*/
+void QMapboxGL::setPaintProperty(const QString& layer, const QString& property, const QVariant& value, const QString& styleClass)
 {
     using namespace mbgl::style;
 
-    Layer* layer = d_ptr->mapObj->getLayer(layer_.toStdString());
-    if (!layer) {
-        qWarning() << "Layer not found:" << layer_;
+    Layer* layer_ = d_ptr->mapObj->getLayer(layer.toStdString());
+    if (!layer_) {
+        qWarning() << "Layer not found:" << layer;
         return;
     }
 
     mbgl::optional<std::string> klass;
-    if (!klass_.isEmpty()) {
-        klass = klass_.toStdString();
+    if (!styleClass.isEmpty()) {
+        klass = styleClass.toStdString();
     }
 
-    if (conversion::setPaintProperty(*layer, property.toStdString(), value, klass)) {
-        qWarning() << "Error setting paint property:" << layer_ << "-" << property;
+    if (conversion::setPaintProperty(*layer_, property.toStdString(), value, klass)) {
+        qWarning() << "Error setting paint property:" << layer << "-" << property;
         return;
     }
 }
 
+/*!
+    Returns true when the map is completely rendered, false otherwise. A partially
+    rendered map ranges from nothing rendered at all to only labels missing.
+*/
 bool QMapboxGL::isFullyLoaded() const
 {
     return d_ptr->mapObj->isFullyLoaded();
 }
 
+/*!
+    Pan the map by \a offset in pixels.
+
+    The pixel coordinate origin is located at the upper left corner of the map.
+*/
 void QMapboxGL::moveBy(const QPointF &offset)
 {
     d_ptr->mapObj->moveBy(mbgl::ScreenCoordinate { offset.x(), offset.y() });
 }
 
+/*!
+    \fn QMapboxGL::scaleBy(double scale, const QPointF &center)
+
+    Scale the map by \a scale in the direction of the \a center. This function
+    can be used for implementing a pinch gesture.
+*/
 void QMapboxGL::scaleBy(double scale_, const QPointF &center) {
     d_ptr->mapObj->scaleBy(scale_, mbgl::ScreenCoordinate { center.x(), center.y() });
 }
 
+/*!
+    Rotate the map from the \a first screen coordinate to the \a second screen coordinate.
+    This method can be used for implementing rotating the map by clicking and dragging,
+    being \a first the cursor coordinate at the last frame and \a second the cursor coordinate
+    at the current frame.
+*/
 void QMapboxGL::rotateBy(const QPointF &first, const QPointF &second)
 {
     d_ptr->mapObj->rotateBy(
@@ -848,6 +1061,17 @@ void QMapboxGL::rotateBy(const QPointF &first, const QPointF &second)
             mbgl::ScreenCoordinate { second.x(), second.y() });
 }
 
+/*!
+    Resize the map to \a size and scale to fit at \a framebufferSize. For
+    high DPI screens, the size will be smaller than the \a framebufferSize.
+
+    This fallowing example will double the pixel density of the map for
+    a given \c size:
+
+    \code
+        map->resize(size / 2, size);
+    \endcode
+*/
 void QMapboxGL::resize(const QSize& size, const QSize& framebufferSize)
 {
     if (d_ptr->size == size && d_ptr->fbSize == framebufferSize) return;
@@ -875,7 +1099,18 @@ void QMapboxGL::addAnnotationIcon(const QString &name, const QImage &icon)
     d_ptr->mapObj->addAnnotationIcon(name.toStdString(), toSpriteImage(icon));
 }
 
-QPointF QMapboxGL::pixelForCoordinate(const Coordinate &coordinate_) const
+/*!
+    \fn QMapboxGL::pixelForCoordinate(const QMapbox::Coordinate &coordinate) const
+
+    Returns the offset in pixels for \a coordinate. The origin pixel coordinate is
+    located at the top left corner of the map view.
+
+    This method returns the correct value for any coordinate, even if the coordinate
+    is not currently visible on the screen.
+
+    /note The return value is affected by the current zoom level, bearing and pitch.
+*/
+QPointF QMapboxGL::pixelForCoordinate(const QMapbox::Coordinate &coordinate_) const
 {
     const mbgl::ScreenCoordinate pixel =
         d_ptr->mapObj->pixelForLatLng(mbgl::LatLng { coordinate_.first, coordinate_.second });
@@ -883,7 +1118,10 @@ QPointF QMapboxGL::pixelForCoordinate(const Coordinate &coordinate_) const
     return QPointF(pixel.x, pixel.y);
 }
 
-Coordinate QMapboxGL::coordinateForPixel(const QPointF &pixel) const
+/*!
+    Returns the geographic coordinate for the \a pixel coordinate.
+*/
+QMapbox::Coordinate QMapboxGL::coordinateForPixel(const QPointF &pixel) const
 {
     const mbgl::LatLng latLng =
         d_ptr->mapObj->latLngForPixel(mbgl::ScreenCoordinate { pixel.x(), pixel.y() });
@@ -891,7 +1129,11 @@ Coordinate QMapboxGL::coordinateForPixel(const QPointF &pixel) const
     return Coordinate(latLng.latitude, latLng.longitude);
 }
 
-CoordinateZoom QMapboxGL::coordinateZoomForBounds(const Coordinate &sw, Coordinate &ne) const
+/*!
+    Returns the coordinate and zoom combination needed in order to make the coordinate
+    bounding box \a sw and \a ne visible.
+*/
+QMapbox::CoordinateZoom QMapboxGL::coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne) const
 {
     auto bounds = mbgl::LatLngBounds::hull(mbgl::LatLng { sw.first, sw.second }, mbgl::LatLng { ne.first, ne.second });
     mbgl::CameraOptions camera = d_ptr->mapObj->cameraForLatLngBounds(bounds, d_ptr->margins);
@@ -899,8 +1141,13 @@ CoordinateZoom QMapboxGL::coordinateZoomForBounds(const Coordinate &sw, Coordina
     return {{ (*camera.center).latitude, (*camera.center).longitude }, *camera.zoom };
 }
 
-CoordinateZoom QMapboxGL::coordinateZoomForBounds(const Coordinate &sw, Coordinate &ne,
+/*!
+    Returns the coordinate and zoom combination needed in order to make the coordinate
+    bounding box \a sw and \a ne visible taking into account \a newBearing and \a newPitch.
+*/
+QMapbox::CoordinateZoom QMapboxGL::coordinateZoomForBounds(const QMapbox::Coordinate &sw, QMapbox::Coordinate &ne,
     double newBearing, double newPitch)
+
 {
     // FIXME: mbgl::Map::cameraForLatLngBounds should
     // take bearing and pitch as input too, so this
@@ -946,12 +1193,30 @@ QMargins QMapboxGL::margins() const
     );
 }
 
-void QMapboxGL::addSource(const QString &sourceID, const QVariantMap &params)
+/*!
+    Adds a source \a id to the map as specified by the \l
+    {https://www.mapbox.com/mapbox-gl-style-spec/#root-sources}{Mapbox style specification} with
+    \a params.
+
+    This example reads a GeoJSON from the Qt resource system and adds it as source:
+
+    \code
+        QFile geojson(":source1.geojson");
+        geojson.open(QIODevice::ReadOnly);
+
+        QVariantMap routeSource;
+        routeSource["type"] = "geojson";
+        routeSource["data"] = geojson.readAll();
+
+        map->addSource("routeSource", routeSource);
+    \endcode
+*/
+void QMapboxGL::addSource(const QString &id, const QVariantMap &params)
 {
     using namespace mbgl::style;
     using namespace mbgl::style::conversion;
 
-    Result<std::unique_ptr<Source>> source = convert<std::unique_ptr<Source>>(QVariant(params), sourceID.toStdString());
+    Result<std::unique_ptr<Source>> source = convert<std::unique_ptr<Source>>(QVariant(params), id.toStdString());
     if (!source) {
         qWarning() << "Unable to add source:" << source.error().message.c_str();
         return;
@@ -960,14 +1225,20 @@ void QMapboxGL::addSource(const QString &sourceID, const QVariantMap &params)
     d_ptr->mapObj->addSource(std::move(*source));
 }
 
-void QMapboxGL::updateSource(const QString &sourceID, const QVariantMap &params)
+/*!
+    Updates the source \a id with new \a params.
+
+    If the source does not exist, it will be added like in addSource(). Only
+    GeoJSON sources can be updated.
+*/
+void QMapboxGL::updateSource(const QString &id, const QVariantMap &params)
 {
     using namespace mbgl::style;
     using namespace mbgl::style::conversion;
 
-    auto source = d_ptr->mapObj->getSource(sourceID.toStdString());
+    auto source = d_ptr->mapObj->getSource(id.toStdString());
     if (!source) {
-        addSource(sourceID, params);
+        addSource(id, params);
         return;
     }
 
@@ -985,20 +1256,33 @@ void QMapboxGL::updateSource(const QString &sourceID, const QVariantMap &params)
     }
 }
 
-void QMapboxGL::removeSource(const QString& sourceID)
+/*!
+    Removes the source \a id.
+
+    This method has no effect if the source does not exist.
+*/
+void QMapboxGL::removeSource(const QString& id)
 {
-    auto sourceIDStdString = sourceID.toStdString();
+    auto sourceIDStdString = id.toStdString();
 
     if (d_ptr->mapObj->getSource(sourceIDStdString)) {
         d_ptr->mapObj->removeSource(sourceIDStdString);
     }
 }
 
+/*!
+    Adds a custom layer \a id with the initialization function \a initFn, the
+    render function \a renderFn and the deinitialization function \a deinitFn with
+    the user data \a context before the existing layer \a before.
+
+    \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.
+*/
 void QMapboxGL::addCustomLayer(const QString &id,
         QMapbox::CustomLayerInitializeFunction initFn,
         QMapbox::CustomLayerRenderFunction renderFn,
         QMapbox::CustomLayerDeinitializeFunction deinitFn,
-        void *context_,
+        void *context,
         char *before)
 {
     d_ptr->mapObj->addLayer(std::make_unique<mbgl::style::CustomLayer>(
@@ -1008,10 +1292,29 @@ void QMapboxGL::addCustomLayer(const QString &id,
             // CustomLayerRenderParameters members remains the same.
             (mbgl::style::CustomLayerRenderFunction)renderFn,
             reinterpret_cast<mbgl::style::CustomLayerDeinitializeFunction>(deinitFn),
-            context_),
+            context),
             before ? mbgl::optional<std::string>(before) : mbgl::optional<std::string>());
 }
 
+/*!
+    Adds a style layer to the map as specified by the \l
+    {https://www.mapbox.com/mapbox-gl-style-spec/#root-layers}{Mapbox style specification} with
+    \a params.
+
+    This example shows how to add a layer that will be used to show a route line on the map. Note
+    that nothing will be drawn until we set paint properties using setPaintProperty().
+
+    \code
+        QVariantMap route;
+        route["id"] = "route";
+        route["type"] = "line";
+        route["source"] = "routeSource";
+
+        map->addLayer(route);
+    \endcode
+
+    /note The source must exist prior to adding a layer.
+*/
 void QMapboxGL::addLayer(const QVariantMap &params)
 {
     using namespace mbgl::style;
@@ -1026,63 +1329,108 @@ void QMapboxGL::addLayer(const QVariantMap &params)
     d_ptr->mapObj->addLayer(std::move(*layer));
 }
 
+/*!
+    Removes the layer \a id.
+*/
 void QMapboxGL::removeLayer(const QString& id)
 {
     d_ptr->mapObj->removeLayer(id.toStdString());
 }
 
-void QMapboxGL::addImage(const QString &name, const QImage &sprite)
+/*!
+    Adds the \a image with the identifier \a id that can be used
+    later by a symbol layer.
+
+    If the \a id was already added, it gets replaced by the new
+    \a image only if the dimensions of the image are the same as
+    the old image, otherwise it has no effect.
+
+    \sa addLayer()
+*/
+void QMapboxGL::addImage(const QString &id, const QImage &image)
 {
-    if (sprite.isNull()) return;
+    if (image.isNull()) return;
 
-    d_ptr->mapObj->addImage(name.toStdString(), toSpriteImage(sprite));
+    d_ptr->mapObj->addImage(id.toStdString(), toSpriteImage(image));
 }
 
-void QMapboxGL::removeImage(const QString &name)
+/*!
+    Removes the image \a id.
+*/
+void QMapboxGL::removeImage(const QString &id)
 {
-    d_ptr->mapObj->removeImage(name.toStdString());
+    d_ptr->mapObj->removeImage(id.toStdString());
 }
 
-void QMapboxGL::setFilter(const QString& layer_, const QVariant& filter_)
+/*!
+    Adds a \a filter to a style \a layer using the format described in the \l
+    {https://www.mapbox.com/mapbox-gl-style-spec/#types-filter}{Mapbox style specification}.
+
+    Given a layer \c marker from an arbitrary GeoJSON source containing features of type \b
+    "Point" and \b "LineString", this example shows how to make sure the layer will only tag
+    features of type \b "Point".
+
+    \code
+        QVariantList filterExpression;
+        filterExpression.append("==");
+        filterExpression.append("$type");
+        filterExpression.append("Point");
+
+        QVariantList filter;
+        filter.append(filterExpression);
+
+        map->setFilter("marker", filter);
+    \endcode
+*/
+void QMapboxGL::setFilter(const QString& layer, const QVariant& filter)
 {
     using namespace mbgl::style;
     using namespace mbgl::style::conversion;
 
-    Layer* layer = d_ptr->mapObj->getLayer(layer_.toStdString());
-    if (!layer) {
-        qWarning() << "Layer not found:" << layer_;
+    Layer* layer_ = d_ptr->mapObj->getLayer(layer.toStdString());
+    if (!layer_) {
+        qWarning() << "Layer not found:" << layer;
         return;
     }
 
-    Filter filter;
+    Filter filter_;
 
-    Result<Filter> converted = convert<Filter>(filter_);
+    Result<Filter> converted = convert<Filter>(filter);
     if (!converted) {
         qWarning() << "Error parsing filter:" << converted.error().message.c_str();
         return;
     }
-    filter = std::move(*converted);
+    filter_ = std::move(*converted);
 
-    if (layer->is<FillLayer>()) {
-        layer->as<FillLayer>()->setFilter(filter);
+    if (layer_->is<FillLayer>()) {
+        layer_->as<FillLayer>()->setFilter(filter_);
         return;
     }
-    if (layer->is<LineLayer>()) {
-        layer->as<LineLayer>()->setFilter(filter);
+    if (layer_->is<LineLayer>()) {
+        layer_->as<LineLayer>()->setFilter(filter_);
         return;
     }
-    if (layer->is<SymbolLayer>()) {
-        layer->as<SymbolLayer>()->setFilter(filter);
+    if (layer_->is<SymbolLayer>()) {
+        layer_->as<SymbolLayer>()->setFilter(filter_);
         return;
     }
-    if (layer->is<CircleLayer>()) {
-        layer->as<CircleLayer>()->setFilter(filter);
+    if (layer_->is<CircleLayer>()) {
+        layer_->as<CircleLayer>()->setFilter(filter_);
         return;
     }
 
     qWarning() << "Layer doesn't support filters";
 }
 
+/*!
+    Renders the map using OpenGL draw calls. If \a fbo is passed, it will
+    make sure to bind the framebuffer object before drawing; otherwise a
+    valid OpenGL context is expected with an appropriate OpenGL viewport state set
+    for the size of the canvas.
+
+    This function should be called only after the signal needsRendering() is
+    emitted at least once.
+*/
 #if QT_VERSION >= 0x050000
 void QMapboxGL::render(QOpenGLFramebufferObject *fbo)
 {
@@ -1106,11 +1454,42 @@ void QMapboxGL::render()
 }
 #endif
 
+/*!
+    Informs the map that the network connection has been established, causing
+    all network requests that previously timed out to be retried immediately.
+*/
 void QMapboxGL::connectionEstablished()
 {
     d_ptr->connectionEstablished();
 }
 
+/*!
+    \fn void QMapboxGL::needsRendering()
+
+    This signal is emitted when the visual contents of the map have changed
+    and a redraw is needed in order to keep the map visually consistent
+    with the current state.
+
+    \sa render()
+*/
+
+/*!
+    \fn void QMapboxGL::mapChanged(QMapboxGL::MapChange change)
+
+    This signal is emitted when the state of the map has changed. This signal
+    may be used for detecting errors when loading a style or detecting when
+    a map is fully loaded by analyzing the parameter \a change.
+*/
+
+/*!
+    \fn void QMapboxGL::copyrightsChanged(const QString &copyrightsHtml);
+
+    This signal is emitted when the copyrights of the current content of the map
+    have changed. This can be caused by a style change or adding a new source.
+
+    \a copyrightsHtml is a string with a HTML snippet.
+*/
+
 QMapboxGLPrivate::QMapboxGLPrivate(QMapboxGL *q, const QMapboxGLSettings &settings, const QSize &size_, qreal pixelRatio)
     : QObject(q)
     , size(size_)