From 32e03492e61865bf3f79b25f26adf5c239e54209 Mon Sep 17 00:00:00 2001
From: Ulysse Buonomo <buonomo.ulysse@gmail.com>
Date: Tue, 11 Jan 2022 14:02:52 +0100
Subject: [PATCH] Add API documentation (targetting rubydoc.info mostly) (#27)

Currently writing an article on C extensions, I saw that we miss correct documentation
here (rubydoc.info/gems/fast-polylines). I've wrote some documentation, mostly
targetting the C extension to both provide an example for the article and improve our doc :)
---
 .gitignore                          |  3 +++
 .yardopts                           |  7 +++++
 ext/fast_polylines/fast_polylines.c | 41 +++++++++++++++++++++++++++--
 fast-polylines.gemspec              |  4 +--
 lib/fast_polylines.rb               | 10 ++++---
 5 files changed, 57 insertions(+), 8 deletions(-)
 create mode 100644 .yardopts

diff --git a/.gitignore b/.gitignore
index 132e741..f587755 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
 *.gem
 .rubocop-*
 Gemfile.lock
+/.yardoc
+/yardoc
+*.bundle
diff --git a/.yardopts b/.yardopts
new file mode 100644
index 0000000..552d027
--- /dev/null
+++ b/.yardopts
@@ -0,0 +1,7 @@
+--markup markdown
+--output-dir ./yardoc
+lib/**/*.rb
+ext/**/*.c
+-
+README.md
+CHANGELOG.md
diff --git a/ext/fast_polylines/fast_polylines.c b/ext/fast_polylines/fast_polylines.c
index b0e4fd8..140afb6 100644
--- a/ext/fast_polylines/fast_polylines.c
+++ b/ext/fast_polylines/fast_polylines.c
@@ -1,3 +1,24 @@
+/**
+ * Document-module: FastPolylines
+ *
+ * Implementation of the [Google polyline algorithm](https://code.google.com/apis/maps/documentation/utilities/polylinealgorithm.html).
+ *
+ * Install it with `gem install fast-polylines`, and then:
+ *
+ *     require "fast_polylines"
+ *
+ *     FastPolylines.encode([[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]])
+ *     # "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
+ *
+ *     FastPolylines.decode("_p~iF~ps|U_ulLnnqC_mqNvxq`@")
+ *     # [[38.5, -120.2], [40.7, -120.95], [43.252, -126.453]]
+ *
+ * You can set an arbitrary precision for your coordinates to be encoded/decoded. It may be from 1
+ * to 13 decimal digits. However, 13 may be too much.
+ *
+ * [![https://xkcd.com/2170/](https://imgs.xkcd.com/comics/coordinate_precision.png)](https://www.explainxkcd.com/wiki/index.php/2170:_Coordinate_Precision)
+ */
+
 #include <ruby.h>
 
 // An encoded number can have at most _precision_ characters. However,
@@ -46,7 +67,15 @@ static inline uint _get_precision(VALUE value) {
 	return (uint)precision;
 }
 
-static inline VALUE
+/**
+ * call-seq:
+ *   FastPolylines.decode(polyline, precision = 5) -> [[lat, lng], ...]
+ *
+ * Decode a polyline to a list of coordinates (lat, lng tuples). You may
+ * set an arbitrary coordinate precision, however, it **must match** the precision
+ * that was used for encoding.
+ */
+static VALUE
 rb_FastPolylines__decode(int argc, VALUE *argv, VALUE self) {
 	rb_check_arity(argc, 1, 2);
 	Check_Type(argv[0], T_STRING);
@@ -103,7 +132,15 @@ _polyline_encode_number(char *chunks, int64_t number) {
 	return i;
 }
 
-static inline VALUE
+/**
+ * call-seq:
+ *   FastPolylines.encode([[lat, lng], ...], precision = 5) -> string
+ *
+ * Encode a list of coordinates to a polyline, you may give a specific precision
+ * if you want to retain more (or less) than 5 digits of precision. The maximum
+ * is 13, and may really be [too much](https://xkcd.com/2170/).
+ */
+static VALUE
 rb_FastPolylines__encode(int argc, VALUE *argv, VALUE self) {
 	rb_check_arity(argc, 1, 2);
 	Check_Type(argv[0], T_ARRAY);
diff --git a/fast-polylines.gemspec b/fast-polylines.gemspec
index 5d20554..3482693 100644
--- a/fast-polylines.gemspec
+++ b/fast-polylines.gemspec
@@ -14,9 +14,9 @@ Gem::Specification.new do |spec|
   spec.license     = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.4.6")
 
-  spec.files = Dir["{lib,ext}/**/*.{rb,c}"] + %w(README.md CHANGELOG.md)
+  spec.files = Dir["{lib,ext}/**/*.{rb,c}"] + %w(README.md CHANGELOG.md .yardopts)
   spec.extensions = ["ext/fast_polylines/extconf.rb"]
-  spec.test_files =Dir["spec/**/*"] + %w(.rspec)
+  spec.test_files = Dir["spec/**/*"] + %w(.rspec)
   spec.require_paths = "lib"
 
   spec.add_development_dependency("benchmark-ips", "~> 2.7")
diff --git a/lib/fast_polylines.rb b/lib/fast_polylines.rb
index f19d06d..8f033fd 100644
--- a/lib/fast_polylines.rb
+++ b/lib/fast_polylines.rb
@@ -3,17 +3,19 @@
 require "fast_polylines/fast_polylines"
 
 module FastPolylines::Encoder
-  module_function def encode(points, precision = 1e5)
+  # @deprecated Use {FastPolylines.encode} instead.
+  def self.encode(points, precision = 1e5)
     warn "Deprecated use of `FastPolylines::Encoder.encode`, " \
-          "use `FastPolylines.encode`."
+         "use `FastPolylines.encode`."
     FastPolylines.encode(points, Math.log10(precision))
   end
 end
 
 module FastPolylines::Decoder
-  module_function def decode(polyline, precision = 1e5)
+  # @deprecated Use {FastPolylines.decode} instead.
+  def self.decode(polyline, precision = 1e5)
     warn "Deprecated use of `FastPolylines::Decoder.decode`, " \
-          "use `FastPolylines.decode`."
+         "use `FastPolylines.decode`."
     FastPolylines.decode(polyline, Math.log10(precision))
   end
 end