rdoc documentation

lib/vydumschik/address.rb

@@ -1,27 +1,43 @@
 require 'yaml'
 
 module Vydumschik
+
+  # This module generates random addresses
   module Address
+
+    # Maximum number of apartments in building
     MAX_APT = 100
+
+    # Maximum number of buildings for different types of streets 
     BUILDING_LIMITS = {:street => 50, :alley => 10, :avenue => 120, :square => 10, :other => 20}
-    HOUSE_PROBABILITY = 0.2 # probability of address without apartment
-    MODIFIER_PROBABILITY = 0.05 # probability of building number with modifier
+
+    # Probability of building without apartments
+    HOUSE_PROBABILITY = 0.2 
+
+    # Probability of building number having a  modifier
+    MODIFIER_PROBABILITY = 0.05 
+
+    # Building number modifiers
     BUILDING_MODIFIERS = %w(а б в г д)
 
+    # Returns a random street name
     def self.street
       data[:streets][rand data[:streets].length][:name]
     end
 
+    # Returns a random building number
     def self.building(limit = BUILDING_LIMITS[:other])
       bld = (1+rand(limit)).to_s
       bld+='-'+BUILDING_MODIFIERS[rand BUILDING_MODIFIERS.length] if rand<MODIFIER_PROBABILITY
       bld
     end
 
+    # Returns a random apartment number
     def self.apartment
       (1+rand(MAX_APT)).to_s
     end
 
+    # Returns a random street address
     def self.street_address
       street = data[:streets][rand data[:streets].length]
       bld = building(BUILDING_LIMITS[street[:type]])
@@ -33,6 +49,8 @@ def self.street_address
       "#{street[:name]}, #{apt}"
     end
 
+    private_class_method :data
+
     def self.data
       @data ||= YAML.load_file(File.expand_path('../../../data/addresses.yml', __FILE__))
     end

lib/vydumschik/lorem.rb

@@ -1,25 +1,39 @@
-# Warning!
-# To avoid using ActiveSupport for multibyte support, or anything similar, 
-# I just assume that all russian chars are 2-byte (as in UTF8) and that I 
-# always get a russian char when I ask for one.
 
 module Vydumschik
+
+  # This module generate lipsum-like russian pseudosentences.
+  #
+  # Warning!
+  # To avoid using ActiveSupport for multibyte support, or anything similar, 
+  # I just assume that all russian chars are 2-byte (as in UTF8) and that I 
+  # always get a russian char when I ask for one.
   module Lorem
-    WORD_LIMITS = [2, 8]
-    SENTENCE_LIMITS = [5, 5]
-    PARA_LIMITS = [5, 5]
 
+    # Word length
+    WORD_LIMITS = [2, 10]
+
+    # Sentence length, in words
+    SENTENCE_LIMITS = [5, 10]
+
+    # Paragraph length, in sentences
+    PARA_LIMITS = [5, 10]
+
+    # Russian consonants
     CONSONANTS = %w(б в г д ж з й к л м н п р с т ф х ц ч ш щ)
+
+    # Russian vowels
     VOWELS = %w(а е ё и о у ы э ю я)
 
-    # These arrays are normalized by character frequency
+    # Consonants, normalized by character frequency
     CONSONANTS_NORMALIZED = %w(б б б б б б б б б б б б б б б б б б б в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в в г г г г г г г г г г г г г г г г г г г д д д д д д д д д д д д д д д д д д д д д д д д д д д д д д д д ж ж ж ж ж ж ж ж ж ж ж ж з з з з з з з з з з з з з з з з з з й й й й й й й й й й й к к к к к к к к к к к к к к к к к к к к к к к к к к к к к к к к к к к к л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л л м м м м м м м м м м м м м м м м м м м м м м м м м м м м м м м м н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н н п п п п п п п п п п п п п п п п п п п п п п п п п п р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р р с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с с т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т т ф х х х х х х х х ц ц ц ч ч ч ч ч ч ч ч ч ч ч ч ч ч ч ч ч ч ш ш ш ш ш ш ш ш ш щ щ щ)
+
+    # Vowels, normalized by character frequency
     VOWELS_NORMALIZED = %w(а а а а а а а а а а а а а а а а а а а а а а а а а а а а е е е е е е е е е е е е е е е е е е е е е е е е е е е е е е е и и и и и и и и и и и и и и и и и и и и и и о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о о у у у у у у у у у ы ы ы ы ы ы э ю ю я я я я я я я)
 
-
-    def self.word(last_word=nil)
-      if last_word
-        last_char = last_word[-2,2]
+    # Returns a random word. Passing a previous word affects the first character
+    def self.word(previous_word=nil)
+      if previous_word
+        last_char = previous_word[-2,2]
         if CONSONANTS.include?(last_char)
           next_char = VOWELS_NORMALIZED
         else
@@ -37,6 +51,7 @@ def self.word(last_word=nil)
       word
     end
 
+    # Returns a random sentence
     def self.sentence
       last_word = nil
       sentence = []
@@ -46,6 +61,7 @@ def self.sentence
       capitalize_ru(sentence.join(' ')) + '.'
     end
 
+    # Returns a random paragraph
     def self.paragraph
       sentences = []
       random_length(PARA_LIMITS).times do
@@ -54,10 +70,14 @@ def self.paragraph
       sentences.join(' ')
     end
 
+    private_class_method :random_length, capitalize_ru
+
+    # Random value based on limits
     def self.random_length(limits)
-      limits.first + rand(limits.last)
+      limits.first + rand(limits.last-limits.first+1)
     end
 
+    # Capitalizes a russian string. Works only with UTF8.
     def self.capitalize_ru(word)
       w = word.clone
       code = (w[1]-0b10000000) + ((w[0]-0b11000000)<<6)

lib/vydumschik/name.rb

@@ -1,30 +1,39 @@
 require 'yaml'
 
 module Vydumschik
+
+  # This module generates human names
   module Name
+
+    # Random first name (gender = :male/:female/nil for random)
     def self.first_name(gender=nil)
       gender ||= random_gender
       gender == :female ? data[:female][rand data[:female].length] : data[:male][rand data[:male].length][:name]
     end
 
+    # Random middle name (gender = :male/:female/nil for random)
     def self.middle_name(gender=nil)
       gender ||= random_gender
       name = data[:male][rand data[:male].length]
       gender == :female ? name[:female_middle] : name[:male_middle]
     end
 
+    # Random surnamename (gender = :male/:female/nil for random)
     def self.surname(gender=nil)
       gender ||= random_gender
       surname = data[:surnames][rand data[:surnames].length]
       surname += 'а' if gender==:female
       surname
     end
-
+
+    # Random full name - surname, first name and middle name (gender = :male/:female/nil for random)
     def self.full_name(gender=nil)
       gender ||= random_gender
       [surname(gender), first_name(gender), middle_name(gender)].join(' ')
     end
 
+    private_class_method :data, :random_gender
+
     def self.data
       @data ||= YAML.load_file(File.expand_path('../../../data/names.yml', __FILE__))
     end

vydumschik.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Leonid Shevtsov"]
   s.email       = ["leonid@shevtsov.me"]
-  s.homepage    = ""
+  s.homepage    = "https://github.com/leonid-shevtsov/vydumschik"
   s.summary     = %q{A fake data library (Vydumschik is russian for "inventor")}
   s.description = %q{Vydumschik creates fake Cyrillic names, surnames, full names, and lipsum-like text}