Improve docs for t:Calendar.microsecond/0

Author: whatyouhide

lib/elixir/lib/calendar.ex

@@ -58,9 +58,25 @@ defmodule Calendar do
   @typedoc """
   Microseconds with stored precision.
 
-  The precision represents the number of digits that must be used when
+  The `precision` represents the number of digits that must be used when
   representing the microseconds to external format. If the precision is `0`,
-  it means microseconds must be skipped.
+  it means microseconds must be skipped. If the precision is `6`, it means
+  that `value` represents exactly the number of microseconds to be used.
+
+  The formula to calculate microseconds from this type is:
+
+      microseconds = value * Integer.pow(10, 6 - precision)
+
+  ## Examples
+
+    * `{0, 0}` means no microseconds.
+    * `{1, 6}` means 1µs (`value` is `1` and the precision specifies that six digits
+      must be used).
+    * `{93, 3}` means 93ms (`value` is `93` and the precision specifies that three digits
+      must be used).
+    * `{12, 2}` means 120ms (`value` is `12` and the precision specifies that two digits
+      must be used).
+
   """
   @type microsecond :: {value :: non_neg_integer, precision :: non_neg_integer}