feat: 100% documented public members (fleaflet#1838)

* add doc strings

* Minor documentation improvements

* Fixed formatting

* add requested changes

---------

Co-authored-by: Luka S <[email protected]>

analysis_options.yaml

@@ -51,5 +51,4 @@ linter:
     comment_references: true
     parameter_assignments: true
     avoid_unused_constructor_parameters: true
-    # TODO: enable the following lint when all public APIs are documented
-    # public_member_api_docs: true
+    public_member_api_docs: true

lib/src/geo/crs.dart

@@ -20,8 +20,12 @@ abstract class Crs {
   /// Set to true if the CRS has no bounds.
   @nonVirtual
   final bool infinite;
+
+  /// Wrap the longitude to fit inside the bounds of the [Crs].
   @nonVirtual
   final (double, double)? wrapLng;
+
+  /// Wrap the latitude to fit inside the bounds of the [Crs].
   @nonVirtual
   final (double, double)? wrapLat;
 
@@ -38,6 +42,8 @@ abstract class Crs {
 
   /// Scale planar coordinate to scaled map point.
   (double, double) transform(double x, double y, double scale);
+
+  /// Scale map point to planar coordinate.
   (double, double) untransform(double x, double y, double scale);
 
   /// Converts a point on the sphere surface (with a certain zoom) to a
@@ -86,6 +92,7 @@ abstract class CrsWithStaticTransformation extends Crs {
   @override
   (double, double) transform(double x, double y, double scale) =>
       _transformation.transform(x, y, scale);
+
   @override
   (double, double) untransform(double x, double y, double scale) =>
       _transformation.untransform(x, y, scale);
@@ -124,6 +131,7 @@ abstract class CrsWithStaticTransformation extends Crs {
 /// Custom CRS for non geographical maps
 @immutable
 class CrsSimple extends CrsWithStaticTransformation {
+  /// Create a new [CrsSimple].
   const CrsSimple()
       : super._(
           code: 'CRS.SIMPLE',
@@ -202,6 +210,7 @@ class Proj4Crs extends Crs {
         _scales = scales,
         super(wrapLat: null, wrapLng: null);
 
+  /// Create a new [Crs] that has projection.
   factory Proj4Crs.fromFactory({
     required String code,
     required proj4.Projection proj4Projection,
@@ -250,6 +259,7 @@ class Proj4Crs extends Crs {
   @override
   (double, double) transform(double x, double y, double scale) =>
       _getTransformationByZoom(zoom(scale)).transform(x, y, scale);
+
   @override
   (double, double) untransform(double x, double y, double scale) =>
       _getTransformationByZoom(zoom(scale)).untransform(x, y, scale);
@@ -371,10 +381,12 @@ abstract class Projection {
   /// Converts a [LatLng] to geometry coordinates.
   (double, double) projectXY(LatLng latlng);
 
+  /// unproject a cartesian Point to [LatLng].
   @nonVirtual
   LatLng unproject(Point point) =>
       unprojectXY(point.x.toDouble(), point.y.toDouble());
 
+  /// unproject cartesian x,y coordinates to [LatLng].
   LatLng unprojectXY(double x, double y);
 }
 
@@ -395,6 +407,7 @@ class _LonLat extends Projection {
       LatLng(_inclusiveLat(y), _inclusiveLng(x));
 }
 
+/// Spherical mercator projection
 @immutable
 class SphericalMercator extends Projection {
   /// The radius
@@ -414,13 +427,15 @@ class SphericalMercator extends Projection {
   /// Constant constructor for the [SphericalMercator] projection.
   const SphericalMercator() : super(_bounds);
 
+  /// Project the latitude for this [Crs]
   static double projectLat(double latitude) {
     final lat = _clampSym(latitude, maxLatitude);
     final sin = math.sin(lat * math.pi / 180);
 
     return r / 2 * math.log((1 + sin) / (1 - sin));
   }
 
+  /// Project the longitude for this [Crs]
   static double projectLng(double longitude) {
     return r * math.pi / 180 * longitude;
   }

lib/src/gestures/interactive_flag.dart

@@ -27,6 +27,7 @@ abstract class InteractiveFlag {
       scrollWheelZoom |
       rotate;
 
+  /// Disable all gesture interactions
   static const int none = 0;
 
   /// Enable panning with a single finger or cursor

lib/src/gestures/map_interactive_viewer.dart

@@ -136,8 +136,10 @@ class MapInteractiveViewerState extends State<MapInteractiveViewer>
     super.dispose();
   }
 
+  /// Rebuilds the map widget
   void onMapStateChange() => setState(() {});
 
+  /// Handles key down events to detect if one of the trigger keys got pressed.
   bool cursorKeyboardRotationTriggerHandler(KeyEvent event) {
     _ckrTriggered.value = (event is KeyRepeatEvent || event is KeyDownEvent) &&
         (_interactionOptions.cursorKeyboardRotationOptions.isKeyTrigger ??

lib/src/layer/attribution_layer/rich/source.dart

@@ -10,6 +10,12 @@ import 'package:meta/meta.dart';
 sealed class SourceAttribution extends StatelessWidget {
   const SourceAttribution._({super.key, this.onTap});
 
+  /// This callback gets called when the user clicks or taps on the attribution
+  /// source.
+  ///
+  /// Most tile providers will require you to link to their terms of service,
+  /// which may be done through this callback (and a package like
+  /// 'url_launcher').
   final VoidCallback? onTap;
 
   Widget _render(BuildContext context);

lib/src/layer/general/hit_detection.dart

@@ -31,6 +31,7 @@ class LayerHitResult<R extends Object> {
   /// See [coordinate] for the geographical coordinate which was hit.
   final Point<double> point;
 
+  /// Construct a new [LayerHitResult] by providing the values.
   @internal
   const LayerHitResult({
     required this.hitValues,

lib/src/layer/overlay_image_layer/overlay_image.dart

@@ -8,6 +8,9 @@ sealed class BaseOverlayImage extends StatelessWidget {
 
   /// The opacity in which the image should get rendered on the map.
   final double opacity;
+
+  /// Whether to continue showing the old image (true), or briefly show nothing
+  /// (false), when the image provider changes. The default value is false.
   final bool gaplessPlayback;
 
   const BaseOverlayImage({
@@ -44,6 +47,7 @@ sealed class BaseOverlayImage extends StatelessWidget {
 /// bounding box to minimize distortion.
 @immutable
 class OverlayImage extends BaseOverlayImage {
+  /// The latitude / longitude corners of the image.
   final LatLngBounds bounds;
 
   /// Create a new [OverlayImage] used for the [OverlayImageLayer].

lib/src/layer/polygon_layer/polygon.dart

@@ -26,6 +26,9 @@ class Polygon<R extends Object> {
   /// The color of the [Polygon] outline.
   final Color borderColor;
 
+  /// Whether holes should have borders
+  ///
+  /// Defaults to false (enabled).
   final bool disableHolesBorder;
 
   /// Set to true if the border of the [Polygon] should be rendered
@@ -54,7 +57,11 @@ class Polygon<R extends Object> {
     'This feature was deprecated (and the default changed) after v7.',
   )
   final bool? isFilled;
+
+  /// Styles to use for line endings.
   final StrokeCap strokeCap;
+
+  /// Styles to use for line segment joins.
   final StrokeJoin strokeJoin;
 
   /// The optional label of the [Polygon].
@@ -143,6 +150,7 @@ class Polygon<R extends Object> {
   }) : _filledAndClockwise =
             (isFilled ?? (color != null)) && isClockwise(points);
 
+  /// Checks if the [Polygon] points are ordered clockwise in the list.
   static bool isClockwise(List<LatLng> points) {
     double sum = 0;
     for (int i = 0; i < points.length; ++i) {

lib/src/layer/polyline_layer/polyline.dart

@@ -17,12 +17,20 @@ class Polyline<R extends Object> {
 
   /// The [Color] of the [Polyline] border.
   final Color borderColor;
+
+  /// The List of colors in case a gradient should get used.
   final List<Color>? gradientColors;
+
+  /// The stops for the gradient colors.
   final List<double>? colorsStop;
 
   /// Set to true if the line stroke should be rendered as a dotted line.
   final bool isDotted;
+
+  /// Styles to use for line endings.
   final StrokeCap strokeCap;
+
+  /// Styles to use for line segment joins.
   final StrokeJoin strokeJoin;
 
   /// Set to true if the width of the stroke should have meters as unit.
@@ -73,6 +81,7 @@ class Polyline<R extends Object> {
   // Used to batch draw calls to the canvas
   int? _renderHashCode;
 
+  /// A for rendering purposes optimized hashCode function.
   int get renderHashCode => _renderHashCode ??= Object.hash(
         strokeWidth,
         color,

lib/src/layer/scalebar/painter/base.dart

@@ -1,5 +1,9 @@
 part of '../scalebar.dart';
 
+/// This painter is used in the [Scalebar] widget and ensures that all
+/// [ScalebarPainter]s have a function to tell the widget what [Size]
+/// it should have.
 abstract class ScalebarPainter extends CustomPainter {
+  /// The size of the [Scalebar] widget without any padding
   Size get widgetSize;
 }

lib/src/layer/scalebar/scalebar.dart

@@ -147,6 +147,7 @@ const _metricScale = <int>[
   1,
 ];
 
+/// The relative length of the scalebar.
 enum ScalebarLength {
   /// Small scalebar
   s(-2),
@@ -169,6 +170,7 @@ enum ScalebarLength {
   /// south pole.
   xxl(2);
 
+  /// The relative value of the size that gets used for internal calculations.
   final int value;
 
   const ScalebarLength(this.value);

lib/src/layer/tile_layer/retina_mode.dart

@@ -55,6 +55,7 @@ enum RetinaMode {
   /// plugin use by [TileLayer.resolvedRetinaMode].
   simulation('Simulation');
 
+  /// The readable name of the [RetinaMode]
   final String friendlyName;
 
   const RetinaMode(this.friendlyName);

lib/src/layer/tile_layer/tile.dart

@@ -16,6 +16,9 @@ class Tile extends StatefulWidget {
   /// The tile size for the given scale of the map.
   final double scaledTileSize;
 
+  /// Reference to the offset of the top-left corner of the bounding rectangle
+  /// of the [MapCamera]. The origin will not equal the offset of the top-left
+  /// visible pixel when the map is rotated.
   final Point<double> currentPixelOrigin;
 
   /// Creates a new instance of [Tile].

lib/src/layer/tile_layer/tile_bounds/tile_bounds.dart

@@ -4,6 +4,7 @@ import 'package:flutter_map/src/layer/tile_layer/tile_range.dart';
 import 'package:latlong2/latlong.dart';
 import 'package:meta/meta.dart';
 
+/// The bounding box of a tile.
 @immutable
 abstract class TileBounds {
   /// Reference to the coordinate reference system.
@@ -35,6 +36,7 @@ abstract class TileBounds {
     this._latLngBounds,
   );
 
+  /// Create a [TileBoundsAtZoom] for a given [zoom] level.
   TileBoundsAtZoom atZoom(int zoom);
 
   /// Returns true if these bounds may no longer be valid for the given
@@ -60,6 +62,7 @@ class InfiniteTileBounds extends TileBounds {
   TileBoundsAtZoom atZoom(int zoom) => const InfiniteTileBoundsAtZoom();
 }
 
+/// [TileBounds] that have a discrete [LatLngBounds].
 @immutable
 class DiscreteTileBounds extends TileBounds {
   final Map<int, TileBoundsAtZoom> _tileBoundsAtZoomCache = {};
@@ -101,6 +104,7 @@ class DiscreteTileBounds extends TileBounds {
   }
 }
 
+/// [TileBounds] that get wrapped.
 @immutable
 class WrappedTileBounds extends TileBounds {
   final Map<int, WrappedTileBoundsAtZoom> _tileBoundsAtZoomCache = {};

lib/src/layer/tile_layer/tile_bounds/tile_bounds_at_zoom.dart

@@ -2,16 +2,21 @@ import 'package:flutter_map/flutter_map.dart';
 import 'package:flutter_map/src/layer/tile_layer/tile_range.dart';
 import 'package:meta/meta.dart';
 
+/// A bounding box with zoom level.
 @immutable
 abstract class TileBoundsAtZoom {
   /// Create a new [TileBoundsAtZoom] object.
   const TileBoundsAtZoom();
 
+  /// Wrap [TileCoordinates] for the tile bounds.
   TileCoordinates wrap(TileCoordinates coordinates);
 
+  /// Returns a list of [TileCoordinates] that are valid because they are within
+  /// the [TileRange].
   Iterable<TileCoordinates> validCoordinatesIn(DiscreteTileRange tileRange);
 }
 
+/// A infinite tile bounding box.
 @immutable
 class InfiniteTileBoundsAtZoom extends TileBoundsAtZoom {
   /// Create a new [InfiniteTileBoundsAtZoom] object.
@@ -28,8 +33,10 @@ class InfiniteTileBoundsAtZoom extends TileBoundsAtZoom {
   String toString() => 'InfiniteTileBoundsAtZoom()';
 }
 
+/// [TileBoundsAtZoom] that have discrete coordinate bounds.
 @immutable
 class DiscreteTileBoundsAtZoom extends TileBoundsAtZoom {
+  /// The [TileRange] of the [TileBoundsAtZoom].
   final DiscreteTileRange tileRange;
 
   /// Create a new [DiscreteTileBoundsAtZoom] object.
@@ -51,8 +58,10 @@ class DiscreteTileBoundsAtZoom extends TileBoundsAtZoom {
   String toString() => 'DiscreteTileBoundsAtZoom($tileRange)';
 }
 
+/// A bounding box with zoom level that gets wrapped
 @immutable
 class WrappedTileBoundsAtZoom extends TileBoundsAtZoom {
+  /// The range of tiles for the bounding box.
   final DiscreteTileRange tileRange;
 
   /// If true the wrapped axis will not be checked when calling

lib/src/layer/tile_layer/tile_coordinates.dart

@@ -1,7 +1,17 @@
 import 'dart:math';
 
+import 'package:flutter_map/flutter_map.dart';
 import 'package:meta/meta.dart';
 
+/// Tile coordinates identify the position of the tile position for
+/// slippy map tiles. The z coordinate represents the zoom level where the
+/// zoom level of 0 fits the complete world while bigger z values are using
+/// accordingly to the zoom level of the [MapCamera].
+///
+/// For more information see the docs https://docs.fleaflet.dev/getting-started/explanation#slippy-map-convention.
+///
+/// The tile coordinates are based on maths' [Point] class but extended with
+/// the zoom level.
 @immutable
 class TileCoordinates extends Point<int> {
   /// The zoom level of the tile coordinates.

lib/src/layer/tile_layer/tile_display.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/widgets.dart';
 import 'package:flutter_map/flutter_map.dart';
 
+/// Defines how the tile should get displayed on the map.
 @immutable
 sealed class TileDisplay {
   const TileDisplay();
@@ -55,8 +56,12 @@ sealed class TileDisplay {
   }
 }
 
+/// Display the tile instantaneous.
 @immutable
 class InstantaneousTileDisplay extends TileDisplay {
+  /// The optional opacity of the tile.
+  ///
+  /// Defaults to 1.0
   final double opacity;
 
   const InstantaneousTileDisplay._({this.opacity = 1.0})

lib/src/layer/tile_layer/tile_image.dart

@@ -3,6 +3,7 @@ import 'dart:async';
 import 'package:flutter/widgets.dart';
 import 'package:flutter_map/flutter_map.dart';
 
+/// The tile image class
 class TileImage extends ChangeNotifier {
   bool _disposed = false;