Add more docs to DSL.

lib/phony/dsl.rb

@@ -84,26 +84,24 @@ def trunk code, options = {}
     # uses a zero prefix when formatted
     # with format :national.
     #
-    # Options:
-    #  * length: Length of the fixed length NDC.
-    #  * options: Set :zero to false to not add a zero on format :national.
+    # @param [Fixnum] length The length of the fixed length NDC.
+    # @param [Hash] options An options hash (set zero: false to not add a zero on format :national).
     #
-    # Example:
-    #   # France, uses a fixed NDC of size 1.
+    # @return NationalSplitters::Fixed A fixed length national splitter.
+    #
+    # @example France. Uses a fixed NDC of size 1.
     #   country '33', fixed(1) >> split(2,2,2,2)
     #
     def fixed length, options = {}
       options[:zero] = true if options[:zero].nil?
       NationalSplitters::Fixed.instance_for length, options
     end
 
-    # This country does not use an NDC. This rule will always match.
+    # Marks the country as not using an NDC. This rule will always match.
+    #
+    # @return NationalSplitters::None A no-ndc national splitter.
     #
-    # Examples:
-    #   * Denmark
-    #   * Norway
-    #   * Iceland
-    #   (and more)
+    # @example Denmark, Norway, Iceland.
     #
     def none
       NationalSplitters::None.instance_for
@@ -112,11 +110,11 @@ def none
     # If you have a number of (possibly) variable length NDCs
     # that cannot be well expressed via regexp, use this.
     #
-    # Parameters:
-    #   * ndcs A list of ndcs of variable length.
-    #   * Can contain :max_length => number to denote a maximum NDC length.
+    # @param [Array<String>] ndcs A list of NDCs of variable length. Can contain :max_length => number to denote a maximum NDC length.
     #
-    # Example:
+    # @return NationalSplitters::Variable A variable size national splitter.
+    #
+    # @example With two NDCs
     #   country '51',
     #     # If it's either 103 or 105, then split ...
     #     one_of('103', '105') >> split(3,3)
@@ -134,10 +132,11 @@ def one_of *ndcs
     # If you have a number of (possibly) variable length NDCs
     # that can be well expressed via regexp, use this.
     #
-    # Parameters:
-    #   * regex A regexp describing the NDCs (First group must contain the NDC, eg. /^(0\d{2})\d+$/) contains all NDCs with 0xx...
+    # @param [Regexp] regex A Regexp describing the NDCs (First group must contain the NDC, eg. /^(0\d{2})\d+$/) contains all NDCs with 0xx...
+    #
+    # @return NationalSplitters::Regex A regexp-based national splitter.
     #
-    # Example:
+    # @example With several NDC matchers.
     #   country '52',
     #     match(/^(0\d{2})\d+$/)   >> split(2,2,2,2) |
     #     match(/^(33|55|81)\d+$/) >> split(2,2,2,2) |
@@ -158,7 +157,11 @@ def match regex, options = {}
     #
     # Also takes ranges.
     #
-    # Example:
+    # @param [Array<Fixnum>] local The local group sizes to split the local number part into.
+    #
+    # @return LocalSplitters::Fixed A fixed size local splitter.
+    #
+    # @example Splitting in 4 even groups of two digits.
     #   match(/^(0\d{2})\d+$/) >> split(2,2,2,2) # If it matches, split in 4 groups of size 2.
     #
     def split *local
@@ -171,28 +174,30 @@ def split *local
     #
     # Also takes ranges.
     #
-    # Options:
-    #   * fallback A fallback amount of group sizes in case it doesn't match.
+    # @param [Hash] options. Can contain option :fallback A fallback amount of group sizes in case it doesn't match.
     #
-    # Example:
-    #   # Norway
+    # @return LocalSplitters::Regex A regexp-based local splitter.
+    #
+    # @example Norway
     #   country '47',
     #     none >> matched_split(/^[1].*$/   => [3],
     #                           /^[489].*$/ => [3,2,3],
     #                           :fallback   => [2,2,2,2])
     #
     def matched_split options = {}
-      Phony::LocalSplitters::Regex.instance_for options
+      LocalSplitters::Regex.instance_for options
     end
 
     # Validators
     #
 
     # Which NDCs are explicitly invalid?
     #
-    # Takes a regexp or a string.
+    # @param [Regexp, String] A regexp or a string of invalid NDCs.
+    #
+    # @return Validators::NDC An NDC validator 
     #
-    # Example:
+    # @example NANP
     #   country '1',
     #     fixed(3, :zero => false) >> split(3,4),
     #     invalid_ndcs('911') # The regexp /911/ would also work.