From fbcaf5854ac16f0dc47ac2b3c5818c360a5c966b Mon Sep 17 00:00:00 2001
From: Filipe Correia <filipe.lp.correia@gmail.com>
Date: Tue, 26 Jun 2018 19:14:04 +0100
Subject: [PATCH] Adds code samples on the big module to methods that are
 extending classes that are part of the standard library

---
 src/big/big_decimal.cr  | 12 ++++++++++++
 src/big/big_float.cr    | 12 ++++++++++++
 src/big/big_int.cr      | 18 ++++++++++++++++++
 src/big/big_rational.cr | 13 +++++++++++++
 4 files changed, 55 insertions(+)

diff --git a/src/big/big_decimal.cr b/src/big/big_decimal.cr
index 21909c05c7a0..f17468ceab15 100644
--- a/src/big/big_decimal.cr
+++ b/src/big/big_decimal.cr
@@ -426,6 +426,10 @@ struct Int
   include Comparable(BigDecimal)
 
   # Converts `self` to `BigDecimal`.
+  # ```
+  # require "big"
+  # 1212341515125412412412421.to_big_d
+  # ```
   def to_big_d
     BigDecimal.new(self)
   end
@@ -462,6 +466,10 @@ struct Float
   #
   # NOTE: Floats are fundamentally less precise than BigDecimals,
   # which makes conversion to them risky.
+  # ```
+  # require "big"
+  # 1212341515125412412412421.0.to_big_d
+  # ```
   def to_big_d
     BigDecimal.new(self)
   end
@@ -482,6 +490,10 @@ end
 
 class String
   # Converts `self` to `BigDecimal`.
+  # ```
+  # require "big"
+  # "1212341515125412412412421".to_big_d
+  # ```
   def to_big_d
     BigDecimal.new(self)
   end
diff --git a/src/big/big_float.cr b/src/big/big_float.cr
index d7f7161abae6..1a4f3cd4bece 100644
--- a/src/big/big_float.cr
+++ b/src/big/big_float.cr
@@ -280,6 +280,12 @@ struct Number
 end
 
 class String
+  # Converts `self` to a `BigFloat`.
+  #
+  # ```
+  # require "big"
+  # "1234.0".to_big_f
+  # ```
   def to_big_f
     BigFloat.new(self)
   end
@@ -298,6 +304,12 @@ module Math
     {frac, exp}
   end
 
+  # Returns the sqrt of a `BigFloat`.
+  #
+  # ```
+  # require "big"
+  # Math.sqrt((1000_000_000_0000.to_big_f*1000_000_000_00000.to_big_f))
+  # ```
   def sqrt(value : BigFloat)
     BigFloat.new { |mpf| LibGMP.mpf_sqrt(mpf, value) }
   end
diff --git a/src/big/big_int.cr b/src/big/big_int.cr
index 8070d319e6ed..40579d243ad3 100644
--- a/src/big/big_int.cr
+++ b/src/big/big_int.cr
@@ -522,6 +522,10 @@ struct Int
   end
 
   # Returns a `BigInt` representing this integer.
+  # ```
+  # require "big"
+  # 123.to_big_i
+  # ```
   def to_big_i : BigInt
     BigInt.new(self)
   end
@@ -535,6 +539,10 @@ struct Float
   end
 
   # Returns a `BigInt` representing this float (rounded using `floor`).
+  # ```
+  # require "big"
+  # 1212341515125412412412421.0.to_big_i
+  # ```
   def to_big_i : BigInt
     BigInt.new(self)
   end
@@ -544,12 +552,22 @@ class String
   # Returns a `BigInt` from this string, in the given *base*.
   #
   # Raises `ArgumentError` if this string doesn't denote a valid integer.
+  # ```
+  # require "big"
+  # "3a060dbf8d1a5ac3e67bc8f18843fc48".to_big_i(16)
+  # ```
   def to_big_i(base = 10) : BigInt
     BigInt.new(self, base)
   end
 end
 
 module Math
+  # Returns the sqrt of a `BigInt`.
+  #
+  # ```
+  # require "big"
+  # Math.sqrt((1000_000_000_0000.to_big_i*1000_000_000_00000.to_big_i))
+  # ```
   def sqrt(value : BigInt)
     sqrt(value.to_big_f)
   end
diff --git a/src/big/big_rational.cr b/src/big/big_rational.cr
index 089f900287e4..069a36898667 100644
--- a/src/big/big_rational.cr
+++ b/src/big/big_rational.cr
@@ -234,6 +234,10 @@ struct Int
   include Comparable(BigRational)
 
   # Returns a `BigRational` representing this integer.
+  # ```
+  # require "big"
+  # 123.to_big_r
+  # ```
   def to_big_r
     BigRational.new(self, 1)
   end
@@ -263,6 +267,10 @@ struct Float
   include Comparable(BigRational)
 
   # Returns a `BigRational` representing this float.
+  # ```
+  # require "big"
+  # 123.0.to_big_r
+  # ```
   def to_big_r
     BigRational.new(self)
   end
@@ -273,6 +281,11 @@ struct Float
 end
 
 module Math
+  # Returns the sqrt of a `BigRational`.
+  # ```
+  # require "big"
+  # Math.sqrt((1000_000_000_0000.to_big_r*1000_000_000_00000.to_big_r))
+  # ```
   def sqrt(value : BigRational)
     sqrt(value.to_big_f)
   end