From fb308a1ec948881bcd24a35938713f3eb330660f Mon Sep 17 00:00:00 2001
From: Harald Eilertsen <haraldei@anduin.net>
Date: Mon, 2 Feb 2015 13:23:14 +0100
Subject: Add some documentation.

---
 lib/norwegian-postcodes.rb | 56 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/lib/norwegian-postcodes.rb b/lib/norwegian-postcodes.rb
index be77c8e..6aefc98 100644
--- a/lib/norwegian-postcodes.rb
+++ b/lib/norwegian-postcodes.rb
@@ -2,6 +2,7 @@ module PostCodes
 
   require 'norwegian-postcodes/railtie' if defined?(Rails)
 
+  # Correspond to the Norwegian 'Fylke'
   Counties = [
     "ØSTFOLD",
     "AKERSHUS",
@@ -28,24 +29,53 @@ module PostCodes
     "KONTINENTALSOKKELEN"
   ]
 
+  # Class for holding postcode data
   class PostCode
-    attr_reader :postcode, :city, :municipality, :municipality_name, :cat
+    # Four digit post code
+    attr_reader :postcode
 
+    # Name of city
+    attr_reader :city
+
+    # Four digit municipality ('kommune') id
+    attr_reader :municipality
+
+    # Name of municipality ('kommune')
+    attr_reader :municipality_name
+
+    # Category
+    # * 'G' = street address
+    # * 'P' = Postboxes
+    # * 'B' = Both street addresses and postboxes
+    # * 'S' = Service addresses
+    # * 'K' = Customer with its own post code
+    # * 'F' = Multiple uses
+    attr_reader :cat
+
+    # Create a new post code.
+    # This method should generally not be used by users of the library.
     def initialize(postcode, city, muni, muni_name, cat)
       @postcode, @city, @municipality, @municipality_name, @cat = postcode, city, muni, muni_name, cat
     end
 
+    # Return the County ('kommune') from the postcode data.
+    # The returned format is `[county_id, county_name]`
     def county
       code = @municipality[0..1].to_i
       [code, PostCodes.county(code)]
     end
 
+    # Output postcode data in the same format as in the original postcode database.
     def to_s
       [@postcode, @city, @municipality, @municipality_name, @cat].join("\t")
     end
   end
 
   class << self
+
+    # Load the postcode data into memory.
+    #
+    # +file+ is a file name or IO object to read the data from.
     def load(file)
       @postcodes = []
       if file.is_a?(String)
@@ -60,16 +90,28 @@ module PostCodes
       end
     end
 
-    def search(pc)
-      res = @postcodes.bsearch {|x| x.postcode.to_i >= pc.to_i}
+    # Search for a given postcode.
+    #
+    # Takes a 4 digit postcode as a string, and returns an object of
+    # type PostCodes::PostCode, or +nil+ if the postcode was not found.
+    #
+    def search(postcode)
+      res = @postcodes.bsearch {|x| x.postcode.to_i >= postcode.to_i}
       unless res.nil?
-        res.postcode.to_i == pc.to_i ? res : nil
+        res.postcode.to_i == postcode.to_i ? res : nil
       end
     end
 
-    def county(c)
-      return nil unless c > 0 && c <= Counties.size
-      Counties[c - 1]
+    # Return the county by number.
+    #
+    # Takes a number between 1 and 23 as input. This corresponds to the
+    # first two digits in the municipality number.
+    #
+    # The county name as a string is returned.
+    #
+    def county(index)
+      return nil unless index > 0 && index <= Counties.size
+      Counties[index - 1]
     end
   end
 end
-- 
cgit v1.2.3