Doxygen-based documentation for C++ API (#796)

.github/workflows/gh-pages-cpp-api.yml

@@ -0,0 +1,25 @@
+name: gh-pages-cpp-api
+
+on:
+  workflow_dispatch:
+
+jobs:
+  generate-and-deploy-gh-pages-cpp-api:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+
+      - name: Install Doxygen
+        run: sudo apt-get install doxygen -y
+
+      - name: Generate documentation
+        working-directory: docs/doxygen
+        run: doxygen
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4.4.1
+        with:
+          branch: gh-pages
+          folder: docs/doxygen/html
+          target-folder: cpp/api/

.github/workflows/gh-pages-mdbook.yml

@@ -1,13 +1,12 @@
-name: Build documentation
+name: Build & Deploy mdBook documentation
 
 on:
   workflow_dispatch:
 
-
 jobs:
   build-docs:
     name: Build
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v2
       - uses: extractions/setup-just@v1
@@ -17,17 +16,18 @@ jobs:
         shell: bash
         run: sudo apt-get install -y libwayland-dev libxkbcommon-dev # Required for winit
       - name: Build
-        working-directory: docs
+        working-directory: docs/mdbook
         shell: bash
         run: mdbook build
       - uses: actions/upload-artifact@v2
         with:
           name: book
-          path: docs/book/
+          path: docs/mdbook/book/
+
   deploy-docs:
     needs: build-docs
     name: Deploy
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v2
       - name: Download book
@@ -40,4 +40,4 @@ jobs:
         with:
           branch: gh-pages
           folder: artifacts
-          target-folder: docs
+          target-folder: docs/mdbook

.gitmodules

@@ -49,3 +49,6 @@
 [submodule "maplibre-gl-js"]
 	path = maplibre-gl-js
 	url = https://github.com/maplibre/maplibre-gl-js.git
+[submodule "docs/doxygen/doxygen-awesome-css"]
+	path = docs/doxygen/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

docs/doxygen/.gitignore

@@ -0,0 +1 @@
+html

docs/doxygen/MAINPAGE.md

@@ -0,0 +1,5 @@
+# MapLibre GL Native Core Documentation
+
+This is the documentation of the public C++ API of MapLibre GL Native Core. You would normally only use this API if you are a contributor to one of the platform specific APIs. If you want to intergrate use MapLibre GL Native in your project, you are better served by [documentation specific to your platform](https://maplibre.org/projects/maplibre-native/), unless you are interested in the internals of MapLibre GL Native.
+
+The source code can be found [on GitHub](https://github.com/maplibre/maplibre-gl-native) (the `include` directory contains the public API).

docs/doxygen/README.md

@@ -0,0 +1,22 @@
+# Doxygen documentation
+
+This directory contains the files needed to generate the documentation of MapLibre GL Native Core using [Doxygen](https://www.doxygen.nl).
+
+[Doxygen Awesome](https://jothepro.github.io/doxygen-awesome-css/index.html) is used as a theme and is included as a submodule. To update, simply check out a new version of the submodule.
+
+The `[MAINPAGE.md](./MAINPAGE.md)` file contains the contents of the first page you see when you open the documentation website. While `[footer.html](./footer.html)` contains the contents of the footer.
+
+To generate the documentation, run
+
+```
+doxygen
+```
+
+in this directory.
+
+While working on the documentation you might find it useful to run a file server. For example, you can use:
+
+```
+cd html
+python -m http.server
+```

docs/doxygen/footer.html

@@ -0,0 +1,17 @@
+<!-- HTML footer for doxygen 1.9.6-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+  <ul>
+    $navpath
+		<li class="footer"><a href="https://maplibre.org/">MapLibre website</a> | <a href="https://github.com/maplibre/maplibre-gl-native">GitHub repository</a></li>
+  </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>

docs/doxygen/logo.svg

@@ -0,0 +1,10 @@
+<svg width="70" height="70" viewBox="0 0 500 501" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="250" cy="250.383" r="250" fill="#285DAA"/>
+<mask id="mask0_402_73" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="0" y="0" width="500" height="501">
+<circle cx="250" cy="250.383" r="250" fill="#285DAA"/>
+</mask>
+<g mask="url(#mask0_402_73)">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M144.897 176.674C144.897 122.386 192.043 78.2154 250 78.2154C307.957 78.2154 355.103 122.386 355.103 176.674C355.103 258.252 269.153 327.127 255.645 337.951C254.805 338.624 254.245 339.073 254.003 339.286C252.874 340.274 251.437 340.771 250 340.771C248.563 340.771 247.126 340.274 245.997 339.286C245.756 339.073 245.196 338.625 244.357 337.952C230.852 327.131 144.897 258.254 144.897 176.674ZM250 233.72C278.699 233.72 301.963 210.105 301.963 180.976C301.963 151.846 278.699 128.232 250 128.232C221.301 128.232 198.037 151.846 198.037 180.976C198.037 210.105 221.301 233.72 250 233.72Z" fill="#95BEFA"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M190.768 355.337C183.028 355.337 176.752 361.612 176.752 369.353V408.535C176.752 416.276 183.028 422.551 190.768 422.551H309.269C317.01 422.551 323.285 416.276 323.285 408.535V369.353C323.285 361.612 317.01 355.337 309.269 355.337H190.768ZM293.58 380.025H206.457V397.863H293.58V380.025Z" fill="white"/>
+</g>
+</svg>

include/mbgl/actor/actor.hpp

@@ -14,7 +14,7 @@
 
 namespace mbgl {
 
-/*
+/**
     An `Actor<O>` is an owning reference to an asynchronous object of type `O`: an "actor".
     Communication with an actor happens via message passing: you send a message to the object
     (using `invoke`), passing a pointer to the member function to call and arguments which

include/mbgl/actor/actor_ref.hpp

@@ -7,7 +7,7 @@
 
 namespace mbgl {
 
-/*
+/**
     An `ActorRef<O>` is a *non*-owning, weak reference to an actor of type `O`. You can send it
     messages just like an `Actor<O>`. It's a value object: safe to copy and pass between actors
     via messages.
@@ -19,7 +19,6 @@ namespace mbgl {
     the lifetime of the owning Actor, and sending a message to a `Ref` whose `Actor` has died is
     a no-op. (In the future, a dead-letters queue or log may be implemented.)
 */
-
 template <class Object>
 class ActorRef {
 public:

include/mbgl/actor/aspiring_actor.hpp

@@ -17,7 +17,7 @@ class EstablishedActor;
 template <class Object>
 class Actor;
 
-/*
+/**
     An `AspiringActor<O>` is one half of the pair of types that comprise an actor (see `Actor<O>`),
     the other half being `EstablishedActor<O>`.  It is responsible for:
      - ownership of the actor's `Mailbox`

include/mbgl/actor/established_actor.hpp

@@ -12,7 +12,7 @@
 
 namespace mbgl {
 
-/*
+/**
     An `EstablishedActor<O>` is one half of the pair of types that comprise an actor (see `Actor<O>`),
     the other half being `AspiringActor<O>`.  It is responsible for managing the lifetime of the
     target object `O` and the open/closed state of the parent's `mailbox`.
@@ -23,7 +23,6 @@ namespace mbgl {
     similarly executes the `~O` destructor (after closing the mailbox). `EstablishedActor` should
     therefore live entirely on the thread intended to own `O`.
 */
-
 template <class Object>
 class EstablishedActor {
 public:

include/mbgl/actor/mailbox.hpp

@@ -17,17 +17,17 @@ class Message;
 class Mailbox : public std::enable_shared_from_this<Mailbox> {
 public:
    
-    // Create a "holding" mailbox, messages to which will remain queued,
-    // unconsumed, until the mailbox is associated with a Scheduler using
-    // start(). This allows a Mailbox object to be created on one thread and
-    // later transferred to a different target thread that may not yet exist.
+    /// Create a "holding" mailbox, messages to which will remain queued,
+    /// unconsumed, until the mailbox is associated with a Scheduler using
+    /// start(). This allows a Mailbox object to be created on one thread and
+    /// later transferred to a different target thread that may not yet exist.
     Mailbox();
     
     Mailbox(Scheduler&);
 
-    // Attach the given scheduler to this mailbox and begin processing messages
-    // sent to it. The mailbox must be a "holding" mailbox, as created by the
-    // default constructor Mailbox().
+    /// Attach the given scheduler to this mailbox and begin processing messages
+    /// sent to it. The mailbox must be a "holding" mailbox, as created by the
+    /// default constructor Mailbox().
     void open(Scheduler& scheduler_);
     void close();
 

include/mbgl/actor/scheduler.hpp

@@ -11,7 +11,7 @@ namespace mbgl {
 
 class Mailbox;
 
-/*
+/**
     A `Scheduler` is responsible for coordinating the processing of messages by
     one or more actors via their mailboxes. It's an abstract interface. Currently,
     the following concrete implementations exist:
@@ -37,53 +37,53 @@ class Scheduler {
 public:
     virtual ~Scheduler() = default;
 
-    // Enqueues a function for execution.
+    /// Enqueues a function for execution.
     virtual void schedule(std::function<void()>) = 0;
-    // Makes a weak pointer to this Scheduler.
+    /// Makes a weak pointer to this Scheduler.
     virtual mapbox::base::WeakPtr<Scheduler> makeWeakPtr() = 0;
 
-    // Returns a closure wrapping the given one.
-    //
-    // When the returned closure is invoked for the first time, it schedules
-    // the given closure to this scheduler, the consequent calls of the
-    // returned closure are ignored.
-    //
-    // If this scheduler is already deleted by the time the returnded closure is
-    // first invoked, the call is ignored.
+    /// Returns a closure wrapping the given one.
+    ///
+    /// When the returned closure is invoked for the first time, it schedules
+    /// the given closure to this scheduler, the consequent calls of the
+    /// returned closure are ignored.
+    ///
+    /// If this scheduler is already deleted by the time the returnded closure is
+    /// first invoked, the call is ignored.
     std::function<void()> bindOnce(std::function<void()>);
 
-    // Enqueues the given |task| for execution into this scheduler's task queue and
-    // then enqueues the |reply| with the captured task result to the current
-    // task queue.
-    //
-    // The |TaskFn| return type must be compatible with the |ReplyFn| argument type.
-    // Note: the task result is copied and passed by value.
+    /// Enqueues the given |task| for execution into this scheduler's task queue and
+    /// then enqueues the |reply| with the captured task result to the current
+    /// task queue.
+    ///
+    /// The |TaskFn| return type must be compatible with the |ReplyFn| argument type.
+    /// Note: the task result is copied and passed by value.
     template <typename TaskFn, typename ReplyFn>
     void scheduleAndReplyValue(const TaskFn& task, const ReplyFn& reply) {
         assert(GetCurrent());
         scheduleAndReplyValue(task, reply, GetCurrent()->makeWeakPtr());
     }
 
-    // Set/Get the current Scheduler for this thread
+    /// Set/Get the current Scheduler for this thread
     static Scheduler* GetCurrent();
     static void SetCurrent(Scheduler*);
 
-    // Get the scheduler for asynchronous tasks. This method
-    // will lazily initialize a shared worker pool when ran
-    // from the first time.
-    // The scheduled tasks might run in parallel on different
-    // threads.
-    // TODO : Rename to GetPool()
+    /// Get the scheduler for asynchronous tasks. This method
+    /// will lazily initialize a shared worker pool when ran
+    /// from the first time.
+    /// The scheduled tasks might run in parallel on different
+    /// threads.
+    /// TODO : Rename to GetPool()
     static PassRefPtr<Scheduler> GetBackground();
 
-    // Get the *sequenced* scheduler for asynchronous tasks.
-    // Unlike the method above, the returned scheduler
-    // (once stored) represents a single thread, thus each
-    // newly scheduled task is guarantied to run after the
-    // previously scheduled one.
-    //
-    // Sequenced scheduler can be used for running tasks
-    // on the same thread-unsafe object.
+    /// Get the *sequenced* scheduler for asynchronous tasks.
+    /// Unlike the method above, the returned scheduler
+    /// (once stored) represents a single thread, thus each
+    /// newly scheduled task is guarantied to run after the
+    /// previously scheduled one.
+    ///
+    /// Sequenced scheduler can be used for running tasks
+    /// on the same thread-unsafe object.
     static PassRefPtr<Scheduler> GetSequenced();
 
 protected:
@@ -102,4 +102,4 @@ protected:
     }
 };
 
-} // namespace mbgl
+} /// namespace mbgl

include/mbgl/gfx/backend_scope.hpp

@@ -7,10 +7,10 @@ class RendererBackend;
 
 class BackendScope {
 public:
-    // There are two types of scopes: Creating an "Implicit" scope tells Mapbox GL that the
-    // supporting windowing system has already activated the GL Backend and that no further actions
-    // are required. Creating an "Explicit" scope actually enables the GL Backend, and disables it
-    // when the BackendScope is destroyed.
+    /// There are two types of scopes: Creating an "Implicit" scope tells Mapbox GL that the
+    /// supporting windowing system has already activated the GL Backend and that no further actions
+    /// are required. Creating an "Explicit" scope actually enables the GL Backend, and disables it
+    /// when the BackendScope is destroyed.
     enum class ScopeType : bool {
         Implicit,
         Explicit,

include/mbgl/gfx/renderer_backend.hpp

@@ -27,7 +27,7 @@ public:
     RendererBackend(const RendererBackend&) = delete;
     RendererBackend& operator=(const RendererBackend&) = delete;
 
-    // Returns the device's context.
+    /// Returns the device's context.
     Context& getContext();
 
     template <typename T>
@@ -39,20 +39,20 @@ public:
         return contextMode == ContextMode::Shared;
     }
 
-    // Returns a reference to the default surface that should be rendered on.
+    /// Returns a reference to the default surface that should be rendered on.
     virtual Renderable& getDefaultRenderable() = 0;
 
 protected:
     virtual std::unique_ptr<Context> createContext() = 0;
 
-    // Called when the backend's GL context needs to be made active or inactive. These are called,
-    // as a matched pair, exclusively through BackendScope, in two situations:
-    //
-    //   1. When releasing GL resources during Renderer destruction
-    //      (Including calling CustomLayerHost::deinitialize during RenderCustomLayer destruction)
-    //   2. When renderering through Renderer::render()
-    //      (Including calling CustomLayerHost::initialize for newly added custom layers and
-    //       CustomLayerHost::deinitialize on layer removal)
+    /// Called when the backend's GL context needs to be made active or inactive. These are called,
+    /// as a matched pair, exclusively through BackendScope, in two situations:
+    ///
+    ///   1. When releasing GL resources during Renderer destruction
+    ///      (Including calling CustomLayerHost::deinitialize during RenderCustomLayer destruction)
+    ///   2. When renderering through Renderer::render()
+    ///      (Including calling CustomLayerHost::initialize for newly added custom layers and
+    ///       CustomLayerHost::deinitialize on layer removal)
     virtual void activate() = 0;
     virtual void deactivate() = 0;
 

include/mbgl/gl/renderer_backend.hpp

@@ -16,36 +16,36 @@ public:
     RendererBackend(gfx::ContextMode);
     ~RendererBackend() override;
 
-    // Called prior to rendering to update the internally assumed OpenGL state.
+    /// Called prior to rendering to update the internally assumed OpenGL state.
     virtual void updateAssumedState() = 0;
 
 protected:
     std::unique_ptr<gfx::Context> createContext() override;
 
-    // Called with the name of an OpenGL extension that should be loaded. RendererBackend implementations
-    // must call the API-specific version that obtains the function pointer for this function,
-    // or a null pointer if unsupported/unavailable.
+    /// Called with the name of an OpenGL extension that should be loaded. RendererBackend implementations
+    /// must call the API-specific version that obtains the function pointer for this function,
+    /// or a null pointer if unsupported/unavailable.
     virtual ProcAddress getExtensionFunctionPointer(const char*) = 0;
 
-    // Reads the color pixel data from the currently bound framebuffer.
+    /// Reads the color pixel data from the currently bound framebuffer.
     PremultipliedImage readFramebuffer(const Size&);
 
-    // A constant to signal that a framebuffer is bound, but with an unknown ID.
+    /// A constant to signal that a framebuffer is bound, but with an unknown ID.
     static constexpr const FramebufferID ImplicitFramebufferBinding =
         std::numeric_limits<FramebufferID>::max();
 
-    // Tells the renderer that OpenGL state has already been set by the windowing toolkit.
-    // It sets the internal assumed state to the supplied values.
+    /// Tells the renderer that OpenGL state has already been set by the windowing toolkit.
+    /// It sets the internal assumed state to the supplied values.
     void assumeFramebufferBinding(FramebufferID fbo);
     void assumeViewport(int32_t x, int32_t y, const Size&);
     void assumeScissorTest(bool);
 
-    // Returns true when assumed framebuffer binding hasn't changed from the implicit binding.
+    /// Returns true when assumed framebuffer binding hasn't changed from the implicit binding.
     bool implicitFramebufferBound();
 
 public:
-    // Triggers an OpenGL state update if the internal assumed state doesn't match the
-    // supplied values.
+    /// Triggers an OpenGL state update if the internal assumed state doesn't match the
+    /// supplied values.
     void setFramebufferBinding(FramebufferID fbo);
     void setViewport(int32_t x, int32_t y, const Size&);
     void setScissorTest(bool);

include/mbgl/map/map.hpp

@@ -40,13 +40,13 @@ public:
                  const ClientOptions& = ClientOptions());
     ~Map();
 
-    // Register a callback that will get called (on the render thread) when all resources have
-    // been loaded and a complete render occurs.
+    /// Register a callback that will get called (on the render thread) when all resources have
+    /// been loaded and a complete render occurs.
     using StillImageCallback = std::function<void (std::exception_ptr)>;
     void renderStill(StillImageCallback);
     void renderStill(const CameraOptions&, MapDebugOptions, StillImageCallback);
 
-    // Triggers a repaint.
+    /// Triggers a repaint.
     void triggerRepaint();
 
           style::Style& getStyle();
@@ -127,10 +127,10 @@ public:
 
     // Tile prefetching
     //
-    // When loading a map, if `PrefetchZoomDelta` is set to any number greater than 0, the map will
-    // first request a tile for `zoom - delta` in a attempt to display a full map at lower
-    // resolution as quick as possible. It will get clamped at the tile source minimum zoom. The
-    // default `delta` is 4.
+    /// When loading a map, if `PrefetchZoomDelta` is set to any number greater than 0, the map will
+    /// first request a tile for `zoom - delta` in a attempt to display a full map at lower
+    /// resolution as quick as possible. It will get clamped at the tile source minimum zoom. The
+    /// default `delta` is 4.
     void setPrefetchZoomDelta(uint8_t delta);
     uint8_t getPrefetchZoomDelta() const;
 
@@ -141,11 +141,11 @@ public:
     bool isFullyLoaded() const;
     void dumpDebugLogs() const;
 
-    // FreeCameraOptions provides more direct access to the underlying camera entity.
-    // For backwards compatibility the state set using this API must be representable with
-    // `CameraOptions` as well. Parameters are clamped to a valid range or discarded as invalid
-    // if the conversion to the pitch and bearing presentation is ambiguous. For example orientation
-    // can be invalid if it leads to the camera being upside down or the quaternion has zero length.
+    /// FreeCameraOptions provides more direct access to the underlying camera entity.
+    /// For backwards compatibility the state set using this API must be representable with
+    /// `CameraOptions` as well. Parameters are clamped to a valid range or discarded as invalid
+    /// if the conversion to the pitch and bearing presentation is ambiguous. For example orientation
+    /// can be invalid if it leads to the camera being upside down or the quaternion has zero length.
     void setFreeCameraOptions(const FreeCameraOptions& camera);
     FreeCameraOptions getFreeCameraOptions() const;
 

include/mbgl/map/map_observer.hpp

@@ -54,8 +54,8 @@ public:
     virtual void onSourceChanged(style::Source&) {}
     virtual void onDidBecomeIdle() {}
     virtual void onStyleImageMissing(const std::string&) {}
-    // This method should return true if unused image can be removed,
-    // false otherwise. By default, unused image will be removed.
+    /// This method should return true if unused image can be removed,
+    /// false otherwise. By default, unused image will be removed.
     virtual bool onCanRemoveUnusedStyleImage(const std::string&) { return true; }
 };
 

include/mbgl/map/map_options.hpp

@@ -33,8 +33,7 @@ public:
 
     /**
      * @brief Gets the previously set (or default) map mode.
-     *
-     * @return map mode.
+     * @return Returns a #mbgl::MapMode
      */
     MapMode mapMode() const;
 

include/mbgl/map/mode.hpp

@@ -1,3 +1,7 @@
+/**
+ * @file Contains enumerations for various modes
+ */
+
 #pragma once
 
 #include <mbgl/util/util.hpp>
@@ -10,21 +14,21 @@ namespace mbgl {
 using EnumType = uint32_t;
 
 enum class MapMode : EnumType {
-    Continuous, // continually updating map
-    Static, // a once-off still image of an arbitrary viewport
-    Tile // a once-off still image of a single tile
+    Continuous, ///< continually updating map
+    Static, ///< a once-off still image of an arbitrary viewport
+    Tile ///< a once-off still image of a single tile
 };
 
-// We can choose to constrain the map both horizontally or vertically, or only
-// vertically e.g. while panning.
+/// We can choose to constrain the map both horizontally or vertically, or only
+/// vertically e.g. while panning.
 enum class ConstrainMode : EnumType {
     None,
     HeightOnly,
     WidthAndHeight,
 };
 
-// Satisfies embedding platforms that requires the viewport coordinate systems
-// to be set according to its standards.
+/// Satisfies embedding platforms that requires the viewport coordinate systems
+/// to be set according to its standards.
 enum class ViewportMode : EnumType {
     Default,
     FlippedY,

include/mbgl/math/log2.hpp

@@ -11,8 +11,8 @@
 namespace mbgl {
 namespace util {
 
-// Computes the log2(x) rounded up to the next integer.
-// (== number of bits required to store x)
+/// Computes the log2(x) rounded up to the next integer.
+/// (== number of bits required to store x)
 uint32_t ceil_log2(uint64_t x);
 
 template <typename T>

include/mbgl/math/wrap.hpp

@@ -5,8 +5,8 @@
 namespace mbgl {
 namespace util {
 
-// Constrains n to the given range (including min, excluding max) via modular
-// arithmetic.
+/// Constrains n to the given range (including min, excluding max) via modular
+/// arithmetic.
 template <typename T>
 T wrap(T value, T min, T max) {
     if (value >= min && value < max) {

include/mbgl/platform/settings.hpp

@@ -15,25 +15,25 @@ DECLARE_MAPBOX_SETTING(EXPERIMENTAL_THREAD_PRIORITY_FILE, thread_priority_file);
 DECLARE_MAPBOX_SETTING(EXPERIMENTAL_THREAD_PRIORITY_NETWORK, thread_priority_network);
 DECLARE_MAPBOX_SETTING(EXPERIMENTAL_THREAD_PRIORITY_DATABASE, thread_priority_database);
 
-// Settings class provides non-persistent, in-process key-value storage.
+/// Settings class provides non-persistent, in-process key-value storage.
 class Settings final {
 public:
-    // Returns singleton instance
+    /// Returns singleton instance
     static Settings& getInstance() noexcept;
 
-    // Sets setting value for a specified key.
+    /// Sets setting value for a specified key.
     void set(const std::string& key, mapbox::base::Value value) noexcept;
 
-    // Sets multiple setting values by merging current Settings object
-    // with provided `values` object.
+    /// Sets multiple setting values by merging current Settings object
+    /// with provided `values` object.
     void set(const mapbox::base::ValueObject& values) noexcept;
 
-    // Returns setting value for a specified key or NullValue if element
-    // for specified key is missing.
+    /// Returns setting value for a specified key or NullValue if element
+    /// for specified key is missing.
     mapbox::base::Value get(const std::string& key) const noexcept;
 
-    // Returns values for settings whose keys are equal to the ones provided in `keys` argument.
-    // Null values would be provided for keys whose elements are missing in Settings.
+    /// Returns values for settings whose keys are equal to the ones provided in `keys` argument.
+    /// Null values would be provided for keys whose elements are missing in Settings.
     mapbox::base::ValueObject get(const std::vector<std::string>& keys) const noexcept;
 
 private:

include/mbgl/platform/thread.hpp

@@ -3,10 +3,10 @@
 namespace mbgl {
 namespace platform {
 
-// Called when a thread is created
+/// Called when a thread is created
 void attachThread();
 
-// Called when a thread is destroyed
+/// Called when a thread is destroyed
 void detachThread();
 
 } // namespace platform

include/mbgl/renderer/query.hpp

@@ -34,7 +34,7 @@ public:
         : sourceLayers(std::move(sourceLayers_)),
           filter(std::move(filter_)) {}
 
-    // Required for VectorSource, ignored for GeoJSONSource
+    /// Required for VectorSource, ignored for GeoJSONSource
     optional<std::vector<std::string>> sourceLayers;
 
     optional<style::Filter> filter;

include/mbgl/renderer/renderer.hpp

@@ -22,21 +22,21 @@ class RendererBackend;
 } // namespace gfx
 
 struct PlacedSymbolData {
-    // Contents of the label
+    /// Contents of the label
     std::u16string key;
-    // If symbol contains text, text collision box in viewport coordinates
+    /// If symbol contains text, text collision box in viewport coordinates
     optional<mapbox::geometry::box<float>> textCollisionBox;
-    // If symbol contains icon, icon collision box in viewport coordinates
+    /// If symbol contains icon, icon collision box in viewport coordinates
     optional<mapbox::geometry::box<float>> iconCollisionBox;
-    // Symbol text was placed
+    /// Symbol text was placed
     bool textPlaced;
-    // Symbol icon was placed
+    /// Symbol icon was placed
     bool iconPlaced;
-    // Symbol text or icon collision box intersects tile borders
+    /// Symbol text or icon collision box intersects tile borders
     bool intersectsTileBorder;
-    // Viewport padding ({viewportPadding, viewportPadding} is a coordinate of the tile's top-left corner)
+    /// Viewport padding ({viewportPadding, viewportPadding} is a coordinate of the tile's top-left corner)
     float viewportPadding;
-    // Layer id (leader of the symbol layout group)
+    /// Layer id (leader of the symbol layout group)
     std::string layer;
 };
 
@@ -51,7 +51,7 @@ public:
 
     void render(const std::shared_ptr<UpdateParameters>&);
 
-    // Feature queries
+    /// Feature queries
     std::vector<Feature> queryRenderedFeatures(const ScreenLineString&, const RenderedQueryOptions& options = {}) const;
     std::vector<Feature> queryRenderedFeatures(const ScreenCoordinate& point, const RenderedQueryOptions& options = {}) const;
     std::vector<Feature> queryRenderedFeatures(const ScreenBox& box, const RenderedQueryOptions& options = {}) const;
@@ -60,7 +60,7 @@ public:
     AnnotationIDs queryShapeAnnotations(const ScreenBox& box) const;
     AnnotationIDs getAnnotationIDs(const std::vector<Feature>&) const;
 
-    // Feature extension query
+    /// Feature extension query
     FeatureExtensionValue queryFeatureExtensions(const std::string& sourceID,
                                                  const Feature& feature,
                                                  const std::string& extension,

include/mbgl/renderer/renderer_frontend.hpp

@@ -7,24 +7,24 @@ namespace mbgl {
 class RendererObserver;
 class UpdateParameters;
 
-// The RenderFrontend is the bridge between the Map and
-// platform used to update and observer the Renderer
-//
-// It hides any threading specifics and always replies on
-// the original thread.
+/// The RenderFrontend is the bridge between the Map and
+/// platform used to update and observer the Renderer
+///
+/// It hides any threading specifics and always replies on
+/// the original thread.
 class RendererFrontend {
 public:
 
     virtual ~RendererFrontend() = default;
 
-    // Must synchronously clean up the Renderer if set
+    /// Must synchronously clean up the Renderer if set
     virtual void reset() = 0;
 
-    // Implementer must bind the renderer observer to the renderer in a
-    // appropriate manner so that the callbacks occur on the main thread
+    /// Implementer must bind the renderer observer to the renderer in a
+    /// appropriate manner so that the callbacks occur on the main thread
     virtual void setObserver(RendererObserver&) = 0;
 
-    // Coalescing updates is up to the implementer
+    /// Coalescing updates is up to the implementer
     virtual void update(std::shared_ptr<UpdateParameters>) = 0;
 };
 

include/mbgl/renderer/renderer_observer.hpp

@@ -14,25 +14,25 @@ public:
         Full
     };
 
-    // Signals that a repaint is required
+    /// Signals that a repaint is required
     virtual void onInvalidate() {}
 
-    // Resource failed to download / parse
+    /// Resource failed to download / parse
     virtual void onResourceError(std::exception_ptr) {}
 
-    // First frame
+    /// First frame
     virtual void onWillStartRenderingMap() {}
 
-    // Start of frame, initial is the first frame for this map
+    /// Start of frame, initial is the first frame for this map
     virtual void onWillStartRenderingFrame() {}
 
-    // End of frame, booleans flags that a repaint is required and that placement changed.
+    /// End of frame, booleans flags that a repaint is required and that placement changed.
     virtual void onDidFinishRenderingFrame(RenderMode, bool /*repaint*/, bool /*placementChanged*/) {}
 
-    // Final frame
+    /// Final frame
     virtual void onDidFinishRenderingMap() {}
 
-    // Style is missing an image
+    /// Style is missing an image
     using StyleImageMissingCallback = std::function<void()>;
     virtual void onStyleImageMissing(const std::string&, const StyleImageMissingCallback& done) { done(); }
     virtual void onRemoveUnusedStyleImages(const std::vector<std::string>&) {}

include/mbgl/renderer/renderer_state.hpp

@@ -14,22 +14,22 @@ class UpdateParameters;
 class RendererState {
 public:
 
-    // Obtains a CameraOptions out of a given UpdateParameters object.
+    /// Obtains a CameraOptions out of a given UpdateParameters object.
     static CameraOptions getCameraOptions(const UpdateParameters&, const EdgeInsets& = {});
 
-    // Returns whether an image with the given ID exists from a given UpdateParamters object.
+    /// Returns whether an image with the given ID exists from a given UpdateParamters object.
     static bool hasImage(const UpdateParameters&, const std::string& id);
 
-    // Returns whether a layer with the given ID exists from a given UpdateParamters object.
+    /// Returns whether a layer with the given ID exists from a given UpdateParamters object.
     static bool hasLayer(const UpdateParameters&, const std::string& id);
 
-    // Returns whether a source with the given ID exists from a given UpdateParamters object.
+    /// Returns whether a source with the given ID exists from a given UpdateParamters object.
     static bool hasSource(const UpdateParameters&, const std::string& id);
 
-    // Obtains the geographical coordinate out of a given screen coordinate.
+    /// Obtains the geographical coordinate out of a given screen coordinate.
     static ScreenCoordinate pixelForLatLng(const UpdateParameters&, const LatLng&);
 
-    // Obtains the screen coordinate out of a given geographical coordinate.
+    /// Obtains the screen coordinate out of a given geographical coordinate.
     static LatLng latLngForPixel(const UpdateParameters&, const ScreenCoordinate&);
 };
 

include/mbgl/storage/database_file_source.hpp

@@ -16,7 +16,7 @@ public:
     explicit DatabaseFileSource(const ResourceOptions& resourceOptions, const ClientOptions& clientOptions);
     ~DatabaseFileSource() override;
 
-    // FileSource overrides
+    /// FileSource overrides
     std::unique_ptr<AsyncRequest> request(const Resource&, Callback) override;
     void forward(const Resource&, const Response&, std::function<void()> callback) override;
     bool canRequest(const Resource&) const override;
@@ -26,13 +26,13 @@ public:
 
     // Methods common to Ambient cache and Offline functionality
 
-    /*
+    /**
      * Sets path of a database to be used by DatabaseFileSource and invokes provided
      * callback when a database path is set.
      */
     virtual void setDatabasePath(const std::string&, std::function<void()> callback);
 
-    /*
+    /**
      * Delete existing database and re-initialize.
      *
      * When the operation is complete or encounters an error, the given callback will be
@@ -41,7 +41,7 @@ public:
      */
     virtual void resetDatabase(std::function<void(std::exception_ptr)>);
 
-    /*
+    /**
      * Packs the existing database file into a minimal amount of disk space.
      *
      * This operation has a performance impact as it will vacuum the database,
@@ -53,7 +53,7 @@ public:
      */
     virtual void packDatabase(std::function<void(std::exception_ptr)> callback);
 
-    /*
+    /**
      * Sets whether packing the database file occurs automatically after an offline
      * region is deleted (deleteOfflineRegion()) or the ambient cache is cleared
      * (clearAmbientCache()).
@@ -65,7 +65,7 @@ public:
 
     // Ambient cache
 
-    /*
+    /**
      * Insert the provided resource into the ambient cache
      *
      * Consumers of the resource will expect the uncompressed version; the
@@ -76,7 +76,7 @@ public:
      */
     virtual void put(const Resource&, const Response&);
 
-    /*
+    /**
      * Forces revalidation of the ambient cache.
      *
      * Forces Mapbox GL Native to revalidate resources stored in the ambient
@@ -90,7 +90,7 @@ public:
      */
     virtual void invalidateAmbientCache(std::function<void(std::exception_ptr)>);
 
-    /*
+    /**
      * Erase resources from the ambient cache, freeing storage space.
      *
      * Erases the ambient cache, freeing resources.
@@ -103,7 +103,7 @@ public:
      */
     virtual void clearAmbientCache(std::function<void(std::exception_ptr)>);
 
-    /*
+    /**
      * Sets the maximum size in bytes for the ambient cache.
      *
      * This call is potentially expensive because it will try
@@ -127,7 +127,7 @@ public:
 
     // Offline
 
-    /*
+    /**
      * Retrieve all regions in the offline database.
      *
      * The query will be executed asynchronously and the results passed to the given
@@ -136,7 +136,7 @@ public:
      */
     virtual void listOfflineRegions(std::function<void(expected<OfflineRegions, std::exception_ptr>)>);
 
-    /*
+    /**
      * Create an offline region in the database.
      *
      * When the initial database queries have completed, the provided callback will be
@@ -150,24 +150,24 @@ public:
     virtual void createOfflineRegion(const OfflineRegionDefinition& definition,
                                      const OfflineRegionMetadata& metadata,
                                      std::function<void(expected<OfflineRegion, std::exception_ptr>)>);
-    /*
+    /**
      * Update an offline region metadata in the database.
      */
     virtual void updateOfflineMetadata(int64_t regionID,
                                        const OfflineRegionMetadata& metadata,
                                        std::function<void(expected<OfflineRegionMetadata, std::exception_ptr>)>);
 
-    /*
+    /**
      * Register an observer to be notified when the state of the region changes.
      */
     virtual void setOfflineRegionObserver(const OfflineRegion&, std::unique_ptr<OfflineRegionObserver>);
 
-    /*
+    /**
      * Pause or resume downloading of regional resources.
      */
     virtual void setOfflineRegionDownloadState(const OfflineRegion&, OfflineRegionDownloadState);
 
-    /*
+    /**
      * Retrieve the current status of the region. The query will be executed
      * asynchronously and the results passed to the given callback, which will be
      * executed on the database thread; it is the responsibility of the SDK bindings
@@ -176,7 +176,7 @@ public:
     virtual void getOfflineRegionStatus(const OfflineRegion&,
                                         std::function<void(expected<OfflineRegionStatus, std::exception_ptr>)>) const;
 
-    /*
+    /**
      * Merge offline regions from a secondary database into the main offline database.
      *
      * When the database merge is completed, the provided callback will be
@@ -199,7 +199,7 @@ public:
     virtual void mergeOfflineRegions(const std::string& sideDatabasePath,
                                      std::function<void(expected<OfflineRegions, std::exception_ptr>)>);
 
-    /*
+    /**
      * Remove an offline region from the database and perform any resources evictions
      * necessary as a result.
      *
@@ -219,7 +219,7 @@ public:
      */
     virtual void deleteOfflineRegion(const OfflineRegion&, std::function<void(std::exception_ptr)>);
 
-    /*
+    /**
      * Invalidate all the tiles from an offline region forcing Mapbox GL to revalidate
      * the tiles with the server before using. This is more efficient than deleting the
      * offline region and downloading it again because if the data on the cache matches
@@ -227,7 +227,7 @@ public:
      */
     virtual void invalidateOfflineRegion(const OfflineRegion&, std::function<void(std::exception_ptr)>);
 
-    /*
+    /**
      * Changing or bypassing this limit without permission from Mapbox is prohibited
      * by the Mapbox Terms of Service.
      */

include/mbgl/storage/file_source.hpp

@@ -25,10 +25,9 @@ enum FileSourceType : uint8_t {
     FileSystem,
     Network,
     Mbtiles,
-    // Resource loader acts as a proxy and has logic
-    // for request delegation to Asset, Cache, and other
-    // file sources.
-    ResourceLoader
+    ResourceLoader ///< %Resource loader acts as a proxy and has logic
+    /// for request delegation to Asset, Cache, and other
+    /// file sources.
 };
 
 // TODO: Rename to ResourceProvider to avoid confusion with
@@ -40,30 +39,30 @@ public:
 
     using Callback = std::function<void (Response)>;
 
-    // Request a resource. The callback will be called asynchronously, in the same
-    // thread as the request was made. This thread must have an active RunLoop. The
-    // request may be cancelled before completion by releasing the returned AsyncRequest.
-    // If the request is cancelled before the callback is executed, the callback will
-    // not be executed.
+    /// Request a resource. The callback will be called asynchronously, in the same
+    /// thread as the request was made. This thread must have an active RunLoop. The
+    /// request may be cancelled before completion by releasing the returned AsyncRequest.
+    /// If the request is cancelled before the callback is executed, the callback will
+    /// not be executed.
     virtual std::unique_ptr<AsyncRequest> request(const Resource&, Callback) = 0;
 
-    // Allows to forward response from one source to another.
-    // Optionally, callback can be provided to receive notification for forward
-    // operation.
+    /// Allows to forward response from one source to another.
+    /// Optionally, callback can be provided to receive notification for forward
+    /// operation.
     //
     // NOLINTNEXTLINE(performance-unnecessary-value-param)
     virtual void forward(const Resource&, const Response&, std::function<void()>) {}
 
-    // When a file source supports consulting a local cache only, it must return true.
-    // Cache-only requests are requests that aren't as urgent, but could be useful, e.g.
-    // to cover part of the map while loading. The FileSource should only do cheap actions to
-    // retrieve the data, e.g. load it from a cache, but not from the internet.
+    /// When a file source supports consulting a local cache only, it must return true.
+    /// Cache-only requests are requests that aren't as urgent, but could be useful, e.g.
+    /// to cover part of the map while loading. The FileSource should only do cheap actions to
+    /// retrieve the data, e.g. load it from a cache, but not from the internet.
     virtual bool supportsCacheOnlyRequests() const { return false; }
 
-    // Checks whether a resource could be requested from this file source.
+    /// Checks whether a resource could be requested from this file source.
     virtual bool canRequest(const Resource&) const = 0;
 
-    /*
+    /**
      * Pause file request activity.
      *
      * If pause is called then no revalidation or network request activity
@@ -71,7 +70,7 @@ public:
      */
     virtual void pause() {}
 
-    /*
+    /**
      * Resume file request activity.
      *
      * Calling resume will unpause the file source and process any tasks that
@@ -79,23 +78,18 @@ public:
      */
     virtual void resume() {}
 
-    /*
-     * Generic property setter / getter methods.
-     */
+    /// Generic setter method
     virtual void setProperty(const std::string&, const mapbox::base::Value&){};
+    /// Generic getter method
     virtual mapbox::base::Value getProperty(const std::string&) const { return {}; };
 
-    // When supported, sets the modifier of the requested resources.
+    /// When supported, sets the modifier of the requested resources.
     virtual void setResourceTransform(ResourceTransform) {} // NOLINT(performance-unnecessary-value-param)
 
-    // sets the resource options
     virtual void setResourceOptions(ResourceOptions) = 0;
-    // gets the resource options
     virtual ResourceOptions getResourceOptions() = 0;
 
-    // sets the client options
     virtual void setClientOptions(ClientOptions) = 0;
-    // gets the client options
     virtual ClientOptions getClientOptions() = 0;
 
 protected:
@@ -104,22 +98,22 @@ protected:
 
 // Properties that may be supported by online file sources:
 
-// Property name to set / get an access token.
-// type: std::string
+/// Property name to set / get an access token.
+/// type: std::string
 constexpr const char* API_KEY_KEY = "api-tkey";
 
-// Property name to set / get base url.
-// type: std::string
+/// Property name to set / get base url.
+/// type: std::string
 constexpr const char* API_BASE_URL_KEY = "api-base-url";
 
-// Property name to set / get maximum number of concurrent requests.
-// type: unsigned
+/// Property name to set / get maximum number of concurrent requests.
+/// type: unsigned
 constexpr const char* MAX_CONCURRENT_REQUESTS_KEY = "max-concurrent-requests";
 
 // Properties that may be supported by database file sources:
 
-// Property to set database mode. When set, database opens in read-only mode; database opens in read-write-create mode
-// otherwise. type: bool
+/// Property to set database mode. When set, database opens in read-only mode; database opens in read-write-create mode
+/// otherwise. type: bool
 constexpr const char* READ_ONLY_MODE_KEY = "read-only-mode";
 
 } // namespace mbgl

include/mbgl/style/color_ramp_property_value.hpp

@@ -7,7 +7,7 @@
 namespace mbgl {
 namespace style {
 
-/*
+/**
  * Special-case implementation of (a subset of) the PropertyValue<T> interface
  * used for building the HeatmapColor paint property traits class.
  */

include/mbgl/style/conversion_impl.hpp

@@ -21,11 +21,10 @@
 
 namespace mbgl {
 namespace style {
-namespace conversion {
 
-/*
+/**
    The `conversion` namespace defines conversions from JSON structures conforming to the schema defined by
-   the Mapbox Style Specification, to the various C++ types that form the C++ model of that domain:
+   the MapLibre %Style Specification, to the various C++ types that form the C++ model of that domain:
 
        * `std::unique_ptr<Source>`
        * `std::unique_ptr<Layer>`
@@ -89,6 +88,7 @@ namespace conversion {
    `Convertible` itself is movable, but not copyable. A moved-from `Convertible` is in an invalid state;
    you must not do anything with it except let it go out of scope.
 */
+namespace conversion {
 
 template <typename T>
 class ConversionTraits;

include/mbgl/style/expression/compound_expression.hpp

@@ -18,7 +18,7 @@ namespace detail {
 struct SignatureBase;
 } // namespace detail
 
-/*
+/**
     CompoundExpression provides a mechanism for implementing an expression
     simply by providing a list of pure functions of the form
     (const T0& arg0, const T1& arg1, ...) -> Result<U> where T0, T1, ..., U are

include/mbgl/style/expression/dsl.hpp

@@ -12,11 +12,10 @@
 namespace mbgl {
 namespace style {
 namespace expression {
+/// This convenience API does little to no expression validation or type-checking, and is intended for
+/// use only by test and other non-production code.
 namespace dsl {
 
-// This convenience API does little to no expression validation or type-checking, and is intended for
-// use only by test and other non-production code.
-
 template <class... Args>
 std::vector<std::unique_ptr<Expression>> vec(Args... args) {
     std::vector<std::unique_ptr<Expression>> result;

include/mbgl/style/expression/expression.hpp

@@ -129,7 +129,7 @@ public:
     }
 };
 
-/*
+/**
     Expression is an abstract class that serves as an interface and base class
     for particular expression implementations.
 

include/mbgl/style/expression/get_covering_stops.hpp

@@ -9,7 +9,7 @@ namespace mbgl {
 namespace style {
 namespace expression {
 
-// Return the smallest range of stops that covers the interval [lower, upper]
+/// Return the smallest range of stops that covers the interval [lower, upper]
 Range<float> getCoveringStops(const std::map<double, std::unique_ptr<Expression>>& stops, double lower, double upper);
 
 } // namespace expression

include/mbgl/style/expression/is_constant.hpp

@@ -30,7 +30,7 @@ bool isGlobalPropertyConstant(const Expression& expression, const T& properties)
 bool isFeatureConstant(const Expression& expression);
 bool isZoomConstant(const Expression& e);
 
-// Returns true if expression does not depend on information provided by the runtime.
+/// Returns true if expression does not depend on information provided by the runtime.
 bool isRuntimeConstant(const Expression& e);
 
 } // namespace expression

include/mbgl/style/expression/parsing_context.hpp

@@ -53,7 +53,7 @@ public:
 
 } // namespace detail
 
-/*
+/**
     Controls the annotation behavior of the parser when encountering an expression
     whose type is not a subtype of the expected type. The default behavior, used
     when optional<TypeAnnotationOption> is a nullopt, is as follows:
@@ -90,20 +90,20 @@ public:
     const std::vector<ParsingError>& getErrors() const { return *errors; }
     std::string getCombinedErrors() const;
 
-    /*
+    /**
         Parse the given style-spec JSON value as an expression.
     */
     ParseResult parseExpression(const mbgl::style::conversion::Convertible& value,
                                 const optional<TypeAnnotationOption>& = {});
 
-    /*
+    /**
         Parse the given style-spec JSON value as an expression intended to be used
         in a layout or paint property.  This entails checking additional constraints
         that exist in that context but not, e.g., for filters.
     */
     ParseResult parseLayerPropertyExpression(const mbgl::style::conversion::Convertible& value);
 
-    /*
+    /**
         Parse a child expression. For use by individual Expression::parse() methods.
     */
     ParseResult parse(const mbgl::style::conversion::Convertible&,
@@ -111,7 +111,7 @@ public:
                       optional<type::Type> = {},
                       const optional<TypeAnnotationOption>& = {});
 
-    /*
+    /**
         Parse a child expression.  For use by individual Expression::parse() methods.
     */
     ParseResult parse(const mbgl::style::conversion::Convertible&,
@@ -119,7 +119,7 @@ public:
                       optional<type::Type>,
                       const std::map<std::string, std::shared_ptr<Expression>>&);
 
-    /*
+    /**
         Check whether `t` is a subtype of `expected`, collecting an error if not.
      */
     optional<std::string> checkType(const type::Type& t);
@@ -162,7 +162,7 @@ private:
     {}
     
     
-    /*
+    /**
         Parse the given style-spec JSON value into an Expression object.
         Specifically, this function is responsible for determining the expression
         type (either Literal, or the one named in value[0]) and dispatching to the

include/mbgl/style/image.hpp

@@ -49,17 +49,18 @@ public:
 
     const PremultipliedImage& getImage() const;
 
-    // Pixel ratio of the sprite image.
+    /// Pixel ratio of the sprite image.
     float getPixelRatio() const;
 
-    // Whether this image should be interpreted as a signed distance field icon.
+    /// Whether this image should be interpreted as a signed distance field icon.
     bool isSdf() const;
 
-    // Stretch areas of this image.
+    /// Stretch area of this image
     const ImageStretches& getStretchX() const;
+    /// Stretch area of this image
     const ImageStretches& getStretchY() const;
 
-    // The space where text can be fit into this image.
+    /// The space where text can be fit into this image.
     const optional<ImageContent>& getContent() const;
 
     class Impl;

include/mbgl/style/layer.hpp

@@ -117,6 +117,8 @@ public:
     virtual Value serialize() const;
 
     // Private implementation
+    /// @cond FALSE
+
     // TODO : We should not have public mutable data members.
     class Impl;
     Immutable<Impl> baseImpl;

include/mbgl/style/layer_properties.hpp

@@ -13,10 +13,10 @@ namespace style {
 class LayerProperties {
 public:
     virtual ~LayerProperties() = default;
-    // Returns constants mask for the data-driven properties.
+    /// Returns constants mask for the data-driven properties.
     virtual unsigned long constantsMask() const { return 0u; }
     Immutable<Layer::Impl> baseImpl;
-    // Contains render passes used by the renderer, see `mbgl::RenderPass`.
+    /// Contains render passes used by the renderer, see `mbgl::RenderPass`.
     uint8_t renderPasses = 0u;
 
 protected:

include/mbgl/style/layers/background_layer.hpp

@@ -40,6 +40,7 @@ public:
     TransitionOptions getBackgroundPatternTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/circle_layer.hpp

@@ -94,6 +94,7 @@ public:
     TransitionOptions getCircleTranslateAnchorTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/fill_extrusion_layer.hpp

@@ -70,6 +70,7 @@ public:
     TransitionOptions getFillExtrusionVerticalGradientTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/fill_layer.hpp

@@ -70,6 +70,7 @@ public:
     TransitionOptions getFillTranslateAnchorTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/heatmap_layer.hpp

@@ -53,6 +53,7 @@ public:
     TransitionOptions getHeatmapWeightTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/hillshade_layer.hpp

@@ -58,6 +58,7 @@ public:
     TransitionOptions getHillshadeShadowColorTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/line_layer.hpp

@@ -113,6 +113,7 @@ public:
     TransitionOptions getLineWidthTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/location_indicator_layer.hpp

@@ -97,6 +97,7 @@ public:
     TransitionOptions getTopImageSizeTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/raster_layer.hpp

@@ -70,6 +70,7 @@ public:
     TransitionOptions getRasterSaturationTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/layers/symbol_layer.hpp

@@ -275,6 +275,7 @@ public:
     TransitionOptions getTextTranslateAnchorTransition() const;
 
     // Private implementation
+    /// @cond FALSE
 
     class Impl;
     const Impl& impl() const;

include/mbgl/style/position.hpp

@@ -34,7 +34,7 @@ public:
         calculateCartesian();
     };
 
-    // Utility function to be used only during interpolation; this leaves spherical coordinates undefined.
+    /// Utility function to be used only during interpolation; this leaves spherical coordinates undefined.
     void setCartesian(std::array<float, 3>& position_) {
         x = position_[0];
         y = position_[1];

include/mbgl/style/property_expression.hpp

@@ -21,9 +21,9 @@ public:
     Range<float> getCoveringStops(float, float) const noexcept;
     const expression::Expression& getExpression() const noexcept;
 
-    // Can be used for aggregating property expressions from multiple
-    // properties(layers) into single match / case expression. Method may
-    // be removed if a better way of aggregation is found.
+    /// Can be used for aggregating property expressions from multiple
+    /// properties(layers) into single match / case expression. Method may
+    /// be removed if a better way of aggregation is found.
     std::shared_ptr<const expression::Expression> getSharedExpression() const noexcept;
 
     bool useIntegerZoom = false;

include/mbgl/style/source.hpp

@@ -25,8 +25,8 @@ class SourceObserver;
 struct LayerTypeInfo;
 
 /**
- * The runtime representation of a [source](https://www.mapbox.com/mapbox-gl-style-spec/#sources) from the Mapbox Style
- * Specification.
+ * The runtime representation of a [source](https://maplibre.org/maplibre-gl-js-docs/style-spec/sources/)
+ * from the MapLibre Style Specification.
  *
  * `Source` is an abstract base class; concrete derived classes are provided for each source type. `Source` contains
  * functionality that is common to all layer types:
@@ -47,11 +47,11 @@ public:
 
     virtual ~Source();
 
-    // Check whether this source is of the given subtype.
+    /// Check whether this source is of the given subtype.
     template <class T>
     bool is() const;
 
-    // Dynamically cast this source to the given subtype.
+    /// Dynamically cast this source to the given subtype.
     template <class T>
     T* as() {
         return is<T>() ? reinterpret_cast<T*>(this) : nullptr;
@@ -71,6 +71,8 @@ public:
     void setVolatile(bool) noexcept;
 
     // Private implementation
+    /// @cond FALSE
+
     class Impl;
     Immutable<Impl> baseImpl;
 

include/mbgl/util/ignore.hpp

@@ -5,18 +5,16 @@
 namespace mbgl {
 namespace util {
 
-// Accept any number of parameters of any types, and do nothing with them.
-// Useful for providing a context for parameter pack expansion where a legal
-// expansion context is not otherwise available.
-//
-// See https://github.com/mapbox/cpp/blob/master/C%2B%2B%20Structural%20Metaprogramming.md
-// for more details.
-//
+/// Accept any number of parameters of any types, and do nothing with them.
+/// Useful for providing a context for parameter pack expansion where a legal
+/// expansion context is not otherwise available.
+///
+/// See https://github.com/mapbox/cpp/blob/1bb519ef25edd6169f1d6d8a65414044616590a9/docs/structural-metaprogramming.md
+/// for more details.
 template <class... Ts> void ignore(Ts&&...) {}
 
 // std::initializer_list overload, for situations where you need sequenced
 // modifications.
-//
 template <class T> void ignore(const std::initializer_list<T>&) {}
 
 // Handle the zero-argument case.

include/mbgl/util/image.hpp

@@ -14,7 +14,7 @@ namespace mbgl {
 enum class ImageAlphaMode {
     Unassociated,
     Premultiplied,
-    Exclusive, // Alpha-channel only
+    Exclusive, ///< Alpha-channel only
 };
 
 template <ImageAlphaMode Mode>
@@ -81,7 +81,7 @@ public:
         operator=(std::move(newImage));
     }
 
-    // Clears the rect area specified by `pt` and `size` from `dstImage`.
+    /// Clears the rect area specified by `pt` and `size` from `dstImage`.
     static void clear(Image& dstImg, const Point<uint32_t>& pt, const Size& size) {
         if (size.isEmpty()) {
             return;
@@ -106,9 +106,9 @@ public:
         }
     }
 
-    // Copy image data within `rect` from `src` to the rectangle of the same size at `pt`
-    // in `dst`. If the specified bounds exceed the bounds of the source or destination,
-    // throw `std::out_of_range`. Must not be used to move data within a single Image.
+    /// Copy image data within `rect` from `src` to the rectangle of the same size at `pt`
+    /// in `dst`. If the specified bounds exceed the bounds of the source or destination,
+    /// throw `std::out_of_range`. Must not be used to move data within a single Image.
     static void copy(const Image& srcImg, Image& dstImg, const Point<uint32_t>& srcPt, const Point<uint32_t>& dstPt, const Size& size) {
         if (size.isEmpty()) {
             return;

include/mbgl/util/indexed_tuple.hpp

@@ -18,11 +18,10 @@ struct TypeIndex<T, U, Ts...> : std::integral_constant<std::size_t, 1 + TypeInde
 
 template <class...> class IndexedTuple;
 
-// A tuple of Ts, where individual members can be accessed via `t.get<I>()` for I ∈ Is.
-//
-// See https://github.com/mapbox/cpp/blob/master/C%2B%2B%20Structural%20Metaprogramming.md
-// for motivation.
-//
+/// A tuple of Ts, where individual members can be accessed via `t.get<I>()` for I ∈ Is.
+///
+/// See https://github.com/mapbox/cpp/blob/1bb519ef25edd6169f1d6d8a65414044616590a9/docs/structural-metaprogramming.md
+/// for motivation.
 template <class... Is, class... Ts>
 class IndexedTuple<TypeList<Is...>, TypeList<Ts...>> : public std::tuple<Ts...> {
 public:

include/mbgl/util/interpolate.hpp

@@ -81,14 +81,14 @@ public:
 };
 
 
-// In order to accept Array<Number, N> as an output value for Curve
-// expressions, we need to have an interpolatable std::vector type.
-// However, style properties like line-dasharray are represented using
-// std::vector<float>, and should NOT be considered interpolatable.
-// So, we use std::vector<Value> to represent expression array values,
-// asserting that (a) the vectors are the same size, and (b) they contain
-// only numeric values.  (These invariants should be relatively safe,
-// being enforced by the expression type system.)
+/// In order to accept Array<Number, N> as an output value for Curve
+/// expressions, we need to have an interpolatable std::vector type.
+/// However, style properties like line-dasharray are represented using
+/// std::vector<float>, and should NOT be considered interpolatable.
+/// So, we use std::vector<Value> to represent expression array values,
+/// asserting that (a) the vectors are the same size, and (b) they contain
+/// only numeric values.  (These invariants should be relatively safe,
+/// being enforced by the expression type system.)
 template<>
 struct Interpolator<std::vector<style::expression::Value>> {
     std::vector<style::expression::Value> operator()(const std::vector<style::expression::Value>& a,

include/mbgl/util/logging.hpp

@@ -16,8 +16,8 @@ public:
     public:
         virtual ~Observer() = default;
 
-        // When an observer is set, this function will be called for every log
-        // message. Returning true will consume the message.
+        /// When an observer is set, this function will be called for every log
+        /// message. Returning true will consume the message.
         virtual bool onRecord(EventSeverity severity, Event event, int64_t code, const std::string &msg) = 0;
     };
 

include/mbgl/util/pass_types.hpp

@@ -4,7 +4,7 @@
 
 namespace mbgl {
 
-// Using this type as a return type enforces the client to retain the returned object.
+/// Using this type as a return type enforces the client to retain the returned object.
 template <typename T>
 class Pass {
 public:
@@ -21,4 +21,4 @@ private:
 template <typename T>
 using PassRefPtr = Pass<std::shared_ptr<T>>;
 
-} // namespace mbgl
+} // namespace mbgl

include/mbgl/util/platform.hpp

@@ -7,23 +7,23 @@ namespace platform {
 
 class Request;
 
-// Uppercase a string, potentially using platform-specific routines.
+/// Uppercase a string, potentially using platform-specific routines.
 std::string uppercase(const std::string &string);
 
-// Lowercase a string, potentially using platform-specific routines.
+/// Lowercase a string, potentially using platform-specific routines.
 std::string lowercase(const std::string &string);
 
-// Gets the name of the current thread.
+/// Gets the name of the current thread.
 std::string getCurrentThreadName();
 
-// Set the name of the current thread, truncated at 15.
+/// Set the name of the current thread, truncated at 15.
 void setCurrentThreadName(const std::string& name);
 
-// Makes the current thread low priority.
+/// Makes the current thread low priority.
 void makeThreadLowPriority();
 
-// Sets priority of a current thread. Platform implementation
-// must validate provided value.
+/// Sets priority of a current thread. Platform implementation
+/// must validate provided value.
 void setCurrentThreadPriority(double priority);
 
 } // namespace platform

include/mbgl/util/projection.hpp

@@ -35,8 +35,8 @@ public:
     }
 };
 
-// Spherical Mercator projection
-// http://docs.openlayers.org/library/spherical_mercator.html
+/// Spherical Mercator projection
+/// https://github.com/openlayers/docs/blob/c7ab69156e17bedc1059d64d7a864b7868e354c1/library/spherical_mercator.rst
 class Projection {
 public:
     // Map pixel width at given scale.
@@ -78,7 +78,7 @@ public:
         return project_(latLng, worldSize(scale));
     }
 
-    //Returns point on tile
+    /// Returns point on tile
     static Point<double> project(const LatLng& latLng, int32_t zoom) {
         return project_(latLng, 1 << zoom);
     }

include/mbgl/util/run_loop.hpp

@@ -48,11 +48,11 @@ public:
     void runOnce();
     void stop();
 
-    // Platform integration callback for platforms that do not have full
-    // run loop integration or don't want to block at the Mapbox GL Native
-    // loop. It will be called from any thread and is up to the platform
-    // to, after receiving the callback, call RunLoop::runOnce() from the
-    // same thread as the Map object lives.
+    /// Platform integration callback for platforms that do not have full
+    /// run loop integration or don't want to block at the Mapbox GL Native
+    /// loop. It will be called from any thread and is up to the platform
+    /// to, after receiving the callback, call RunLoop::runOnce() from the
+    /// same thread as the Map object lives.
     void setPlatformCallback(std::function<void()> callback) { platformCallback = std::move(callback); }
 
     // So far only needed by the libcurl backend.

include/mbgl/util/thread.hpp

@@ -20,23 +20,22 @@
 namespace mbgl {
 namespace util {
 
-// Manages a thread with `Object`.
-
-// Upon creation of this object, it launches a thread and creates an object of type `Object`
-// in that thread. When the `Thread<>` object is destructed, the destructor waits
-// for thread termination. The `Thread<>` constructor blocks until the thread and
-// the `Object` are fully created, so after the object creation, it's safe to obtain the
-// `Object` stored in this thread. The thread created will always have low priority on
-// the platforms that support setting thread priority.
-//
-// The following properties make this class different from `ThreadPool`:
-//
-// - Only one thread is created.
-// - `Object` will live in a single thread, providing thread affinity.
-// - It is safe to use `ThreadLocal` in an `Object` managed by `Thread<>`
-// - A `RunLoop` is created for the `Object` thread.
-// - `Object` can use `Timer` and do asynchronous I/O, like wait for sockets events.
-//
+/// @brief Manages a thread with `Object`.
+///
+/// Upon creation of this object, it launches a thread and creates an object of type `Object`
+/// in that thread. When the `Thread<>` object is destructed, the destructor waits
+/// for thread termination. The `Thread<>` constructor blocks until the thread and
+/// the `Object` are fully created, so after the object creation, it's safe to obtain the
+/// `Object` stored in this thread. The thread created will always have low priority on
+/// the platforms that support setting thread priority.
+///
+/// The following properties make this class different from `ThreadPool`:
+///
+/// - Only one thread is created.
+/// - `Object` will live in a single thread, providing thread affinity.
+/// - It is safe to use `ThreadLocal` in an `Object` managed by `Thread<>`
+/// - A `RunLoop` is created for the `Object` thread.
+/// - `Object` can use `Timer` and do asynchronous I/O, like wait for sockets events.
 template <typename Object>
 class Thread {
 public:
@@ -101,18 +100,18 @@ public:
         thread.join();
     }
 
-    // Returns a non-owning reference to `Object` that
-    // can be used to send messages to `Object`. It is safe
-    // to the non-owning reference to outlive this object
-    // and be used after the `Thread<>` gets destroyed.
+    /// Returns a non-owning reference to `Object` that
+    /// can be used to send messages to `Object`. It is safe
+    /// to the non-owning reference to outlive this object
+    /// and be used after the `Thread<>` gets destroyed.
     ActorRef<std::decay_t<Object>> actor() {
         return object.self();
     }
 
-    // Pauses the `Object` thread. It will prevent the object to wake
-    // up from events such as timers and file descriptor I/O. Messages
-    // sent to a paused `Object` will be queued and only processed after
-    // `resume()` is called.
+    /// Pauses the `Object` thread. It will prevent the object to wake
+    /// up from events such as timers and file descriptor I/O. Messages
+    /// sent to a paused `Object` will be queued and only processed after
+    /// `resume()` is called.
     void pause() {
         MBGL_VERIFY_THREAD(tid);
 
@@ -161,9 +160,9 @@ private:
     util::RunLoop* loop = nullptr;
 };
 
-// Returns function, that once invoked, will set a thread priority for
-// a thread `threadType` based on a setting provided by corresponding
-// Settings' platform::EXPERIMENTAL_THREAD_PRIORITY_* value.
+/// Returns function, that once invoked, will set a thread priority for
+/// a thread `threadType` based on a setting provided by corresponding
+/// Settings' platform::EXPERIMENTAL_THREAD_PRIORITY_* value.
 std::function<void()> makeThreadPrioritySetter(std::string threadType);
 
 } // namespace util

include/mbgl/util/unitbezier.hpp

@@ -32,7 +32,7 @@ namespace mbgl {
 namespace util {
 
 struct UnitBezier {
-    // Calculate the polynomial coefficients, implicit first and last control points are (0,0) and (1,1).
+    /// Calculate the polynomial coefficients, implicit first and last control points are (0,0) and (1,1).
     constexpr UnitBezier(double p1x, double p1y, double p2x, double p2y)
         : cx(3.0 * p1x)
         , bx(3.0 * (p2x - p1x) - (3.0 * p1x))
@@ -66,7 +66,7 @@ struct UnitBezier {
         return (3.0 * ax * t + 2.0 * bx) * t + cx;
     }
 
-    // Given an x value, find a parametric value it came from.
+    /// Given an x value, find a parametric value it came from.
     double solveCurveX(double x, double epsilon) const {
         double t0;
         double t1;

include/mbgl/util/work_task.hpp

@@ -6,9 +6,9 @@
 
 namespace mbgl {
 
-// A movable type-erasing function wrapper. This allows to store arbitrary invokable
-// things (like std::function<>, or the result of a movable-only std::bind()) in the queue.
-// Source: http://stackoverflow.com/a/29642072/331379
+/// A movable type-erasing function wrapper. This allows to store arbitrary invokable
+/// things (like std::function<>, or the result of a movable-only std::bind()) in the queue.
+/// Source: http://stackoverflow.com/a/29642072/331379
 class WorkTask : private util::noncopyable {
 public:
     virtual ~WorkTask() = default;

include/mbgl/util/work_task_impl.hpp

@@ -24,14 +24,14 @@ public:
         }
     }
 
-    // If the task has not yet begun, this will cancel it.
-    // If the task is in progress, this will block until it completed. (Currently
-    // necessary because of shared state, but should be removed.) It will also
-    // cancel the after callback.
-    // If the task has completed, but the after callback has not executed, this
-    // will cancel the after callback.
-    // If the task has completed and the after callback has executed, this will
-    // do nothing.
+    /// If the task has not yet begun, this will cancel it.
+    /// If the task is in progress, this will block until it completed. (Currently
+    /// necessary because of shared state, but should be removed.) It will also
+    /// cancel the after callback.
+    /// If the task has completed, but the after callback has not executed, this
+    /// will cancel the after callback.
+    /// If the task has completed and the after callback has executed, this will
+    /// do nothing.
     void cancel() override {
         std::lock_guard<std::recursive_mutex> lock(mutex);
         *canceled = true;

src/mbgl/renderer/buckets/fill_extrusion_bucket.cpp

@@ -120,8 +120,9 @@ void FillExtrusionBucket::addFeature(const GeometryTileFeature& feature,
                     const auto d2 = convertPoint<double>(p2);
 
                     const Point<double> perp = util::unit(util::perp(d1 - d2));
-                    const auto dist = util::dist<int16_t>(d1, d2);
-                    if (edgeDistance + dist > std::numeric_limits<int16_t>::max()) {
+                    const size_t dist = util::dist<int16_t>(d1, d2);
+                    if (edgeDistance + dist >
+                        static_cast<size_t>(std::numeric_limits<int16_t>::max())) {
                         edgeDistance = 0;
                     }