Merge pull request #7 from RespiteSage/feature/docs

Add class and method documentation

src/geojson/coordinates.cr

@@ -1,25 +1,37 @@
 module GeoJSON
+  # A `Coordinates` is a position in longitude, latitude, and (optionally)
+  # altitude.
+  #
+  # This class corresponds to the [GeoJSON Position](https://tools.ietf.org/html/rfc7946#section-3.1.1).
   class Coordinates
     getter coordinates : Array(Float64)
 
+    # Creates a new `Coordinates` with the given *coordinates* array.
     def initialize(@coordinates : Array(Float64))
       raise_if_invalid
     end
 
+    # Deserializes a `Coordinates` from the given JSON *parser*.
     def initialize(parser : JSON::PullParser)
       @coordinates = Array(Float64).new(parser)
 
       raise_if_invalid
     end
 
+    # Gets this Coordinates' longitude in decimal degrees according to WGS84.
     def longitude
       coordinates[0]
     end
 
+    # Gets this Coordinates' latitude in decimal degrees according to WGS84.
     def latitude
       coordinates[1]
     end
 
+    # Gets this Coordinates' altitude.
+    #
+    # Technically, this positional value is meant to be the height in meters
+    # above the WGS84 ellipsoid.
     def altitude
       coordinates[2]?
     end

src/geojson/exception.cr

@@ -1,4 +1,8 @@
 module GeoJSON
+  # Raised when an attempt is made to create a GeoJSON object that is malformed.
+  #
+  # In most cases, this means that the given coordinates for a geometry object
+  # don't fulfill the requirements for that geometry type.
   class Exception < Exception
   end
 end

src/geojson/feature.cr

@@ -1,18 +1,25 @@
 require "./object"
 
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.2
+  # A `Feature` represents a [GeoJSON Feature object](https://tools.ietf.org/html/rfc7946#section-3.2)
+  # with a geometry and properties.
   class Feature < Object
+    # Gets this Feature's GeoJSON type ("Feature")
     getter type : String = "Feature"
 
     @[JSON::Field(emit_null: true)]
+    # Gets this Feature's geometry.
     getter geometry : GeoJSON::Object::Type?
 
     @[JSON::Field(emit_null: true)]
+    # Gets this Feature's properties.
     getter properties : Hash(String, JSON::Any::Type)?
 
+    # Gets this Feature's id.
     getter id : String | Int32 | Nil
 
+    # Creates a new `Feature` with the given *geometry* and optional
+    # *properties*, *id*, and bounding box *bbox*.
     def initialize(@geometry, @properties = nil, *, @id = nil, @bbox = nil)
     end
   end

src/geojson/feature_collection.cr

@@ -1,10 +1,14 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.3
+  # A `FeatureCollection` represents a [GeoJSON FeatureCollection object](https://tools.ietf.org/html/rfc7946#section-3.3)
+  # and contains one or more `Feature`s.
   class FeatureCollection < Object
+    # Gets this FeatureCollection's GeoJSON type ("FeatureCollection")
     getter type : String = "FeatureCollection"
 
+    # Returns this `FeatureCollections` array of features.
     getter features : Array(Feature)
 
+    # Creates a new `FeatureCollection` with the given *features*.
     def initialize(@features : Array(Feature), *, @bbox = nil)
     end
   end

src/geojson/geometry_collection.cr

@@ -1,14 +1,26 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.1.8
+  # A `GeometryCollection` represents a collection of several geometries.
+  #
+  # Its array of geometries can contain `Point`, `MultiPoint`, `LineString`,
+  # `MultiLineString`, `Polygon`, and `MultiPolygon`. Technically, you can nest
+  # `GeometryCollection`s inside one another, but this is discouraged by the
+  # specification.
+  #
+  # This class corresponds to the [GeoJSON GeometryCollection](https://tools.ietf.org/html/rfc7946#section-3.1.8).
   class GeometryCollection < Object
+    # Gets this GeometryCollection's GeoJSON type ("GeometryCollection")
     getter type : String = "GeometryCollection"
 
+    # Returns an array of the geometries in this `GeometryCollection`
     getter geometries : Array(GeoJSON::Object::Type) = Array(GeoJSON::Object::Type).new
 
+    # Creates a new `GeometryCollection` containing the given *geometries* and
+    # optional bounding box *bbox*.
     def initialize(geometries : Array(GeoJSON::Object::Type), *, @bbox = nil)
       @geometries += geometries
     end
 
+    # Deserializes a `GeometryCollection` from the given JSON *parser*.
     def self.new(pull : JSON::PullParser)
       geometries = [] of GeoJSON::Object::Type
       pull.read_begin_object

src/geojson/line_string.cr

@@ -1,22 +1,32 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.1.4
+  # A `LineString` is a `Geometry` representing two or more points in geographic
+  # space connected consecutively by lines.
+  #
+  # This class corresponds to the [GeoJSON LineString](https://tools.ietf.org/html/rfc7946#section-3.1.4).
   class LineString < Object
+    # Gets this LineString's GeoJSON type ("LineString")
     getter type : String = "LineString"
 
+    # Gets this LineString's GeoJSON type ("LineString")
     getter coordinates : Array(Coordinates)
 
+    # Gets the LineString vertex at the given index.
     delegate "[]", to: coordinates
 
+    # Create a new `LineString` with the given *coordinates* and optional
+    # bounding box *bbox*.
     def initialize(@coordinates : Array(Coordinates), *, @bbox = nil)
       raise_if_invalid
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Point), *, @bbox = nil)
       @coordinates = coordinates.map { |point| point.coordinates }
 
       raise_if_invalid
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Array(Float64)), *, @bbox = nil)
       @coordinates = coordinates.map { |e| Coordinates.new(e) }
 

src/geojson/multi_line_string.cr

@@ -1,26 +1,36 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.1.5
+  # A `MultiLineString` is a `Geometry` representing several `LineString`s.
+  #
+  # This class corresponds to the [GeoJSON MultiLineString](https://tools.ietf.org/html/rfc7946#section-3.1.5).
   class MultiLineString < Object
+    # Gets this MultiLineString's GeoJSON type ("MultiLineString")
     getter type : String = "MultiLineString"
 
+    # Returns an array of this MultiLineString's coordinates.
     getter coordinates : Array(Array(GeoJSON::Coordinates))
 
+    # Gets the `LineString` at the given index.
     delegate "[]", to: coordinates
 
+    # Create a new `MultiLineString` with the given *coordinates* and optional
+    # bounding box *bbox*.
     def initialize(coordinates : Array(LineString), *, @bbox = nil)
       @coordinates = coordinates.map(&.coordinates)
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Array(Array(Float64))), *, @bbox = nil)
       @coordinates = coordinates.map do |arry|
         LineString.new(arry).coordinates
       end
     end
 
+    # Adds the given *line_string* to this MultiLineString.
     def <<(line_string : Array(LineString))
       @coordinates << line_string
     end
 
+    # Adds the given *coordinate* to this MultiLineString.
     def <<(coordinate : Array(Array(Float64)))
       @coordinates << LineString.new(coordinate).coordinates
     end

src/geojson/multi_point.cr

@@ -1,26 +1,36 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.1.3
+  # A `MultiPoint` is a `Geometry` representing several `Point`s.
+  #
+  # This class corresponds to the [GeoJSON MultiPoint](https://tools.ietf.org/html/rfc7946#section-3.1.3).
   class MultiPoint < Object
+    # Gets this MultiPoint's GeoJSON type ("MultiPoint")
     getter type : String = "MultiPoint"
 
+    # Returns an array of this MultiPoint's coordinates.
     getter coordinates : Array(Coordinates)
 
+    # Gets the `Point` at the given index.
     delegate "[]", to: coordinates
 
+    # Create a new `MultiPoint` with the given *coordinates* and optional
+    # bounding box *bbox*.
     def initialize(coordinates : Array(Point), *, @bbox = nil)
       @coordinates = coordinates.map(&.coordinates)
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Array(Float64)), *, @bbox = nil)
       @coordinates = coordinates.map do |coordinates|
         Point.new(coordinates).coordinates
       end
     end
 
+    # Adds the given *point* to this MultiPoint.
     def <<(point : Array(Point))
       @coordinates << point.coordinates
     end
 
+    # Adds the given *coordinate* to this MultiPoint.
     def <<(coordinate : Array(Float64))
       @coordinates << Point.new(coordinate).coordinates
     end

src/geojson/multi_polygon.cr

@@ -1,26 +1,36 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.1.7
+  # A `MultiPolygon` is a `Geometry` representing several `Polygon`s.
+  #
+  # This class corresponds to the [GeoJSON MultiPolygon](https://tools.ietf.org/html/rfc7946#section-3.1.7).
   class MultiPolygon < Object
+    # Gets this MultiPolygon's GeoJSON type ("MultiPolygon")
     getter type : String = "MultiPolygon"
 
+    # Returns an array of this MultiPolygon's coordinates.
     getter coordinates : Array(Array(Array(GeoJSON::Coordinates)))
 
+    # Gets the `Polygon` at the given index.
     delegate "[]", to: coordinates
 
+    # Create a new `MultiPolygon` with the given *coordinates* and optional
+    # bounding box *bbox*.
     def initialize(coordinates : Array(Polygon), *, @bbox = nil)
       @coordinates = coordinates.map(&.coordinates)
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Array(Array(Array(Float64)))), *, @bbox = nil)
       @coordinates = coordinates.map do |arry|
         Polygon.new(arry).coordinates
       end
     end
 
+    # Adds the given *polygon* to this MultiPolygon.
     def <<(polygon : Array(Polygon))
       @coordinates << polygon.coordinates
     end
 
+    # Adds the given *coordinate* to this MultiPolygon.
     def <<(coordinate : Array(Array(Array(Float64))))
       @coordinates << Polygon.new(coordinate).coordinates
     end

src/geojson/point.cr

@@ -1,10 +1,17 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.1.2
+  # A `Point` is a `Geometry` representing a single `Position` in geographic
+  # space.
+  #
+  # This class corresponds to the [GeoJSON Point](https://tools.ietf.org/html/rfc7946#section-3.1.2).
   class Point < Object
+    # Gets this Point's GeoJSON type ("Point")
     getter type : String = "Point"
 
+    # Returns this Point's coordinates.
     getter coordinates : Coordinates
 
+    # Creates a new `Point` at the given *longitude*, *latitude*, and optional
+    # *altitude*, and with optional bounding box *bbox*.
     def initialize(*, longitude, latitude, altitude = nil, @bbox = nil)
       if altitude
         @coordinates = Coordinates.new([longitude, latitude, altitude])
@@ -13,15 +20,24 @@ module GeoJSON
       end
     end
 
+    # Creates a new `Point` with the given *coordinates* and optional bounding
+    # box *bbox*.
     def initialize(@coordinates : GeoJSON::Coordinates, *, @bbox = nil)
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Float64), *, @bbox = nil)
       @coordinates = GeoJSON::Coordinates.new(coordinates)
     end
 
+    # Gets this Point's longitude in decimal degrees according to WGS84.
     delegate longitude, to: coordinates
+    # Gets this Point's latitude in decimal degrees according to WGS84.
     delegate latitude, to: coordinates
+    # Gets this Point's altitude.
+    #
+    # Technically, this positional value is meant to be the height in meters
+    # above the WGS84 ellipsoid.
     delegate altitude, to: coordinates
 
     def_equals_and_hash coordinates

src/geojson/polygon.cr

@@ -1,14 +1,22 @@
 module GeoJSON
-  # https://tools.ietf.org/html/rfc7946#section-3.1.6
+  # A `Polygon` is a `Geometry` representing a closed geometric figure in
+  # geographic space with optional holes within it.
+  #
+  # This class corresponds to the [GeoJSON Polygon](https://tools.ietf.org/html/rfc7946#section-3.1.6).
   class Polygon < Object
+    # Gets this Polygon's GeoJSON type ("Polygon")
     getter type : String = "Polygon"
 
+    # Returns this Polygon's linear ring coordinates.
     getter coordinates : Array(Array(Coordinates))
 
+    # Creates a new `Polygon` with the given *coordinates* and optional bounding
+    # box *bbox*.
     def initialize(@coordinates : Array(Array(Coordinates)), *, @bbox = nil)
       raise_if_invalid
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Array(Point)), *, @bbox = nil)
       @coordinates = coordinates.map do |ring|
         ring.map { |point| point.coordinates }
@@ -17,6 +25,7 @@ module GeoJSON
       raise_if_invalid
     end
 
+    # :ditto:
     def initialize(coordinates : Array(Array(Array(Float64))), *, @bbox = nil)
       @coordinates = coordinates.map do |ring|
         ring.map { |e| Coordinates.new(e) }