From 6b1fdd87bddf97e9be6a94b9a4fcf99df8c62abb Mon Sep 17 00:00:00 2001
From: Dmitry Afanasyev <dimarzio1986@gmail.com>
Date: Tue, 23 Dec 2014 17:55:55 +0300
Subject: [PATCH] functions docs

---
 addresses.go         |  9 +++++++++
 credit_cards.go      |  5 ++++-
 currencies.go        |  2 ++
 dates.go             | 18 +++++++++++-------
 fake.go              | 13 ++++++++++---
 general.go           | 11 ++++++++++-
 geo.go               | 10 ++++++++++
 internet.go          | 11 ++++++++++-
 jobs.go              |  3 +++
 lorem_ipsum.go       | 15 ++++++++++++++-
 names.go             | 27 +++++++++++++++++++++++++++
 personal.go          |  3 +++
 products.go          |  4 ++++
 test/dates_test.go   |  6 ++----
 test/general_test.go |  4 ++--
 15 files changed, 121 insertions(+), 20 deletions(-)

diff --git a/addresses.go b/addresses.go
index 292f712..4ef4011 100644
--- a/addresses.go
+++ b/addresses.go
@@ -2,14 +2,17 @@ package fake
 
 import "strconv"
 
+// Continent generates random continent
 func Continent() string {
 	return lookup(lang, "continents", true)
 }
 
+// Country generates random country
 func Country() string {
 	return lookup(lang, "countries", true)
 }
 
+// City generates random city
 func City() string {
 	city := lookup(lang, "cities", true)
 	switch r.Intn(5) {
@@ -30,19 +33,23 @@ func citySuffix() string {
 	return lookup(lang, "city_suffixes", false)
 }
 
+// State generates random state
 func State() string {
 	return lookup(lang, "states", false)
 }
 
+// StateAbbrev generates random state abbreviation
 func StateAbbrev() string {
 	return lookup(lang, "state_abbrevs", false)
 }
 
+// Street generates random street name
 func Street() string {
 	street := lookup(lang, "streets", true)
 	return join(street, streetSuffix())
 }
 
+// StreetAddress generates random street name along with building number
 func StreetAddress() string {
 	return join(Street(), strconv.Itoa(r.Intn(100)))
 }
@@ -51,10 +58,12 @@ func streetSuffix() string {
 	return lookup(lang, "street_suffixes", true)
 }
 
+// Zip generates random zip code using one of the formats specifies in zip_format file
 func Zip() string {
 	return generate(lang, "zips", true)
 }
 
+// Phone generates random phone number using one of the formats format specified in phone_format file
 func Phone() string {
 	return generate(lang, "phones", true)
 }
diff --git a/credit_cards.go b/credit_cards.go
index 0be41a2..47d6ca7 100644
--- a/credit_cards.go
+++ b/credit_cards.go
@@ -19,6 +19,8 @@ var creditCards = map[string]creditCard{
 	"discover":   {"Discover", 16, []int{6011}},
 }
 
+// CreditCardType returns one of the following credit values:
+// VISA, MasterCard, American Express and Discover
 func CreditCardType() string {
 	n := len(creditCards)
 	var vendors []string
@@ -29,12 +31,13 @@ func CreditCardType() string {
 	return vendors[r.Intn(n)]
 }
 
+// CreditCardNum generated credit card number according to the card number rules
 func CreditCardNum(vendor string) string {
 	if vendor != "" {
 		vendor = strings.ToLower(vendor)
 	} else {
 		var vendors []string
-		for v, _ := range creditCards {
+		for v := range creditCards {
 			vendors = append(vendors, v)
 		}
 		vendor = vendors[r.Intn(len(vendors))]
diff --git a/currencies.go b/currencies.go
index ae0ad91..b85c943 100644
--- a/currencies.go
+++ b/currencies.go
@@ -1,9 +1,11 @@
 package fake
 
+// Currency generates currency name
 func Currency() string {
 	return lookup(lang, "currencies", true)
 }
 
+// CurrencyCode generates currency code
 func CurrencyCode() string {
 	return lookup(lang, "currency_codes", true)
 }
diff --git a/dates.go b/dates.go
index 32025d2..a5e1d94 100644
--- a/dates.go
+++ b/dates.go
@@ -1,38 +1,42 @@
 package fake
 
-import (
-	"time"
-)
-
+// Day generates day of the month
 func Day() int {
 	return r.Intn(31) + 1
 }
 
+// WeekDay generates name ot the week day
 func WeekDay() string {
 	return lookup(lang, "weekdays", true)
 }
 
+// WeekDayShort generates abbreviated name of the week day
 func WeekDayShort() string {
 	return lookup(lang, "weekdays_short", true)
 }
 
+// WeekdayNum generates number of the day of the week
 func WeekdayNum() int {
 	return r.Intn(7) + 1
 }
 
+// Month generates month name
 func Month() string {
 	return lookup(lang, "months", true)
 }
 
+// MonthShort generates abbreviated month name
 func MonthShort() string {
 	return lookup(lang, "months_short", true)
 }
 
+// MonthNum generates month number (from 1 to 12)
 func MonthNum() int {
 	return r.Intn(12) + 1
 }
 
-func Year(fromOffset, toOffset int) int {
-	n := r.Intn(fromOffset+toOffset) + 1
-	return (time.Now().Year() - fromOffset) + n
+// Year generates year using the given boundaries
+func Year(from, to int) int {
+	n := r.Intn(to-from) + 1
+	return from + n
 }
diff --git a/fake.go b/fake.go
index d5e9d54..c89d1bf 100644
--- a/fake.go
+++ b/fake.go
@@ -1,3 +1,4 @@
+// Package fake is the fake data generatror for go (Golang), heavily inspired by forgery and ffaker Ruby gems
 package fake
 
 import (
@@ -20,11 +21,13 @@ var enFallback = true
 var availLangs = GetLangs()
 
 var (
-	ErrInsufficientParams = fmt.Errorf("Insufficient params to lookup the samples")
-	ErrNoLanguageFn       = func(lang string) error { return fmt.Errorf("The language passed (%s) is not available", lang) }
-	ErrNoSamplesFn        = func(lang string) error { return fmt.Errorf("No samples found for language: %s", lang) }
+	// ErrNoLanguageFn is the error that indicates that given language is not available
+	ErrNoLanguageFn = func(lang string) error { return fmt.Errorf("The language passed (%s) is not available", lang) }
+	// ErrNoSamplesFn is the error that indicates that there are no samples for the given language
+	ErrNoSamplesFn = func(lang string) error { return fmt.Errorf("No samples found for language: %s", lang) }
 )
 
+// GetLangs returns a slice of available languages
 func GetLangs() []string {
 	var langs []string
 	for k, v := range data {
@@ -35,6 +38,8 @@ func GetLangs() []string {
 	return langs
 }
 
+// SetLang sets the language in which the data should be generated
+// returns error if passed language is not available
 func SetLang(newLang string) error {
 	found := false
 	for _, l := range availLangs {
@@ -50,10 +55,12 @@ func SetLang(newLang string) error {
 	return nil
 }
 
+// UseExternalData sets the flag that allows using of external files as data providers (fake uses embedded ones by default)
 func UseExternalData(flag bool) {
 	useExternalData = flag
 }
 
+// EnFallback sets the flag that allows fake to fallback to englsh samples if the ones for the used languaged are not available
 func EnFallback(flag bool) {
 	enFallback = flag
 }
diff --git a/general.go b/general.go
index e60855e..8b1ec7c 100644
--- a/general.go
+++ b/general.go
@@ -29,18 +29,24 @@ func text(atLeast, atMost int, allowLower, allowUpper, allowNumeric, allowSpecia
 	return string(result)
 }
 
+// Password generates password with the length from atLeast to atMOst charachers,
+// allow* parameters specify whether corresponding symbols can be used
 func Password(atLeast, atMost int, allowUpper, allowNumeric, allowSpecial bool) string {
 	return text(atLeast, atMost, true, allowUpper, allowNumeric, allowSpecial)
 }
 
+// SimplePassword is a wrapper around Password,
+// it generates password with the length from 6 to 12 symbols, with upper characters and numeric symbols allowed
 func SimplePassword() string {
 	return Password(6, 12, true, true, false)
 }
 
+// Color generates color name
 func Color() string {
 	return lookup(lang, "colors", true)
 }
 
+// DigitsN returns n digits as a string
 func DigitsN(n int) string {
 	digits := make([]rune, n)
 	for i := 0; i < n; i++ {
@@ -49,6 +55,7 @@ func DigitsN(n int) string {
 	return string(digits)
 }
 
+// Digits returns from 1 to 5 digits as a string
 func Digits() string {
 	return DigitsN(r.Intn(5) + 1)
 }
@@ -61,10 +68,12 @@ func hexDigitsStr(n int) string {
 	return string(num)
 }
 
+// HexColor generates hex color name
 func HexColor() string {
 	return hexDigitsStr(6)
 }
 
-func ShortHexColor() string {
+// HexColorShort generates short hex color name
+func HexColorShort() string {
 	return hexDigitsStr(3)
 }
diff --git a/geo.go b/geo.go
index 2e2aa35..1c6c585 100644
--- a/geo.go
+++ b/geo.go
@@ -1,21 +1,26 @@
 package fake
 
+// Latitute generates latitude
 func Latitute() float32 {
 	return r.Float32() * 180 / 90
 }
 
+// LatitudeDegress generates latitude degrees (from -180 to 180)
 func LatitudeDegress() int {
 	return r.Intn(360) - 180
 }
 
+// LatitudeMinutes generates latitude minutes (from 0 to 60)
 func LatitudeMinutes() int {
 	return r.Intn(60)
 }
 
+// LatitudeSeconds generates latitude seconds (from 0 to 60)
 func LatitudeSeconds() int {
 	return r.Intn(60)
 }
 
+// LatitudeDirection generates latitude direction (N(orth) o S(outh))
 func LatitudeDirection() string {
 	if r.Intn(2) == 0 {
 		return "N"
@@ -23,22 +28,27 @@ func LatitudeDirection() string {
 	return "S"
 }
 
+// Longitude generates longitude
 func Longitude() float32 {
 	return r.Float32()*360 - 180
 }
 
+// LongitudeDegrees generates longitude degrees (from -180 to 180)
 func LongitudeDegrees() int {
 	return r.Intn(360) - 180
 }
 
+// LongitudeMinutes generates (from 0 to 60)
 func LongitudeMinutes() int {
 	return r.Intn(60)
 }
 
+// LongitudeSeconds generates (from 0 to 60)
 func LongitudeSeconds() int {
 	return r.Intn(60)
 }
 
+// LongitudeDirection generates (W(est) or E(ast))
 func LongitudeDirection() string {
 	if r.Intn(2) == 0 {
 		return "W"
diff --git a/internet.go b/internet.go
index 49b7b1a..28ed20b 100644
--- a/internet.go
+++ b/internet.go
@@ -5,9 +5,11 @@ import (
 	"strings"
 )
 
+// UserName generates user name in one of the following forms
+// first name + last name, letter + last names or concatenation of from 1 to 3 lowercased words
 func UserName() string {
 	gender := randGender()
-	switch r.Intn(2) {
+	switch r.Intn(3) {
 	case 0:
 		return lookup("en", gender+"_first_names", false) + lookup(lang, gender+"_last_names", false)
 	case 1:
@@ -17,30 +19,37 @@ func UserName() string {
 	}
 }
 
+// TopLevelDomain generates random top level domain
 func TopLevelDomain() string {
 	return lookup(lang, "top_level_domains", true)
 }
 
+// DomainName generates random domain name
 func DomainName() string {
 	return Company() + "." + TopLevelDomain()
 }
 
+// EmailAddress generates email address
 func EmailAddress() string {
 	return UserName() + "@" + DomainName()
 }
 
+// EmailSubject generates random email subject
 func EmailSubject() string {
 	return Sentence()
 }
 
+// EmailBody generates random email body
 func EmailBody() string {
 	return Paragraphs()
 }
 
+// DomainZone generates random domain zone
 func DomainZone() string {
 	return lookup(lang, "domain_zones", true)
 }
 
+// IPv4 generates IPv4 address
 func IPv4() string {
 	ip := make([]string, 4)
 	for i := 0; i < 4; i++ {
diff --git a/jobs.go b/jobs.go
index a75575f..a497e5d 100644
--- a/jobs.go
+++ b/jobs.go
@@ -1,9 +1,11 @@
 package fake
 
+// Company generates company name
 func Company() string {
 	return lookup(lang, "companies", true)
 }
 
+// JobTitle generates job title
 func JobTitle() string {
 	job := lookup(lang, "jobs", true)
 	return join(job, jobTitleSuffix())
@@ -13,6 +15,7 @@ func jobTitleSuffix() string {
 	return lookup(lang, "jobs_suffixes", false)
 }
 
+// Industry generates industry name
 func Industry() string {
 	return lookup(lang, "industries", true)
 }
diff --git a/lorem_ipsum.go b/lorem_ipsum.go
index 303fac4..8386d5a 100644
--- a/lorem_ipsum.go
+++ b/lorem_ipsum.go
@@ -4,10 +4,12 @@ import (
 	"strings"
 )
 
+// Character generates random character in the given language
 func Character() string {
 	return lookup(lang, "characters", true)
 }
 
+// CharactersN generates n random characters in the given language
 func CharactersN(n int) string {
 	var chars []string
 	for i := 0; i < n; i++ {
@@ -16,14 +18,17 @@ func CharactersN(n int) string {
 	return strings.Join(chars, "")
 }
 
+// Characters generates from 1 to 5 characters in the given language
 func Characters() string {
 	return CharactersN(r.Intn(5) + 1)
 }
 
+// Word generates random word
 func Word() string {
 	return lookup(lang, "words", true)
 }
 
+// WordsN generates n random words
 func WordsN(n int) string {
 	words := make([]string, n)
 	for i := 0; i < n; i++ {
@@ -32,14 +37,17 @@ func WordsN(n int) string {
 	return strings.Join(words, " ")
 }
 
+// Words generates from 1 to 5 random words
 func Words() string {
 	return WordsN(r.Intn(5) + 1)
 }
 
+// Title generates from 2 to 5 titleized words
 func Title() string {
-	return strings.ToTitle(WordsN(2 + r.Intn(3)))
+	return strings.ToTitle(WordsN(2 + r.Intn(4)))
 }
 
+// Sentence generates random sentence
 func Sentence() string {
 	var words []string
 	for i := 0; i < 3+r.Intn(12); i++ {
@@ -61,6 +69,7 @@ func Sentence() string {
 	return sentence
 }
 
+// SentencesN generates n random sentences
 func SentencesN(n int) string {
 	sentences := make([]string, n)
 	for i := 0; i < n; i++ {
@@ -69,14 +78,17 @@ func SentencesN(n int) string {
 	return strings.Join(sentences, " ")
 }
 
+// Sentences generates from 1 to 5 random sentences
 func Sentences() string {
 	return SentencesN(r.Intn(5) + 1)
 }
 
+// Paragraph generates paragraph
 func Paragraph() string {
 	return SentencesN(r.Intn(10) + 1)
 }
 
+// ParagraphsN generates n paragraphs
 func ParagraphsN(n int) string {
 	var paragraphs []string
 	for i := 0; i < n; i++ {
@@ -85,6 +97,7 @@ func ParagraphsN(n int) string {
 	return strings.Join(paragraphs, "\t")
 }
 
+// Paragraphs generates from 1 to 5 paragraphs
 func Paragraphs() string {
 	return ParagraphsN(r.Intn(5) + 1)
 }
diff --git a/names.go b/names.go
index 929e01c..fde3eaf 100644
--- a/names.go
+++ b/names.go
@@ -12,14 +12,17 @@ func firstName(gender string) string {
 	return lookup(lang, gender+"_first_names", true)
 }
 
+// MaleFirstName generates male first name
 func MaleFirstName() string {
 	return firstName("male")
 }
 
+// FemaleFirstName generates female first name
 func FemaleFirstName() string {
 	return firstName("female")
 }
 
+// FirstName generates first name
 func FirstName() string {
 	return firstName(randGender())
 }
@@ -28,14 +31,17 @@ func lastName(gender string) string {
 	return lookup(lang, gender+"_last_names", true)
 }
 
+// MaleLastName generates male last name
 func MaleLastName() string {
 	return lastName("male")
 }
 
+// FemaleLastName generates female last name
 func FemaleLastName() string {
 	return lastName("female")
 }
 
+// LastName generates last name
 func LastName() string {
 	return lastName(randGender())
 }
@@ -44,14 +50,17 @@ func patronymic(gender string) string {
 	return lookup(lang, gender+"_patronymics", false)
 }
 
+// MalePatronymic generates male patronymic
 func MalePatronymic() string {
 	return patronymic("male")
 }
 
+// FemalePatronymic generates female patronymic
 func FemalePatronymic() string {
 	return patronymic("female")
 }
 
+// Patronymic generates patronymic
 func Patronymic() string {
 	return patronymic(randGender())
 }
@@ -68,14 +77,20 @@ func fullNameWithPrefix(gender string) string {
 	return join(prefix(gender), firstName(gender), lastName(gender))
 }
 
+// MaleFullNameWithPrefix generates prefixed male full name
+// if prefixes for the given language are available
 func MaleFullNameWithPrefix() string {
 	return fullNameWithPrefix("male")
 }
 
+// FemaleFullNameWithPrefix generates prefixed female full name
+// if prefixes for the given language are available
 func FemaleFullNameWithPrefix() string {
 	return fullNameWithPrefix("female")
 }
 
+// FullNameWithPrefix generates prefixed full name
+// if prefixes for the given language are available
 func FullNameWithPrefix() string {
 	return fullNameWithPrefix(randGender())
 }
@@ -84,14 +99,20 @@ func fullNameWithSuffix(gender string) string {
 	return join(firstName(gender), lastName(gender), suffix(gender))
 }
 
+// MaleFullNameWithSuffix generates suffixed male full name
+// if suffixes for the given language are available
 func MaleFullNameWithSuffix() string {
 	return fullNameWithPrefix("male")
 }
 
+// FemaleFullNameWithSuffix generates suffixed female full name
+// if suffixes for the given language are available
 func FemaleFullNameWithSuffix() string {
 	return fullNameWithPrefix("female")
 }
 
+// FullNameWithSuffix generates suffixed full name
+// if suffixes for the given language are available
 func FullNameWithSuffix() string {
 	return fullNameWithPrefix(randGender())
 }
@@ -107,14 +128,20 @@ func fullName(gender string) string {
 	}
 }
 
+// MaleFullName generates male full name
+// it can occasionally include prefix or suffix
 func MaleFullName() string {
 	return fullName("male")
 }
 
+// FemaleFullName generates female full name
+// it can occasionally include prefix or suffix
 func FemaleFullName() string {
 	return fullName("female")
 }
 
+// FullName generates full name
+// it can occasionally include prefix or suffix
 func FullName() string {
 	return fullName(randGender())
 }
diff --git a/personal.go b/personal.go
index 55340de..57aa252 100644
--- a/personal.go
+++ b/personal.go
@@ -4,10 +4,12 @@ import (
 	"strings"
 )
 
+// Gender generates random gender
 func Gender() string {
 	return lookup(lang, "genders", true)
 }
 
+// GenderAbbrev returns first downcased letter of the random gender
 func GenderAbbrev() string {
 	g := Gender()
 	if g != "" {
@@ -16,6 +18,7 @@ func GenderAbbrev() string {
 	return ""
 }
 
+// Language generates random human language
 func Language() string {
 	return lookup(lang, "languages", true)
 }
diff --git a/products.go b/products.go
index 1ffd8fb..9c45fb3 100644
--- a/products.go
+++ b/products.go
@@ -1,9 +1,11 @@
 package fake
 
+// Brand generates brand name
 func Brand() string {
 	return Company()
 }
 
+// ProductName generates product name
 func ProductName() string {
 	productName := lookup(lang, "adjectives", true) + " " + lookup(lang, "nouns", true)
 	if r.Intn(2) == 1 {
@@ -12,10 +14,12 @@ func ProductName() string {
 	return productName
 }
 
+// Product generates product title as brand + product name
 func Product() string {
 	return Brand() + " " + ProductName()
 }
 
+// Model generates model name that consists of letters and digits, optionally with a hyphen between them
 func Model() string {
 	seps := []string{"", " ", "-"}
 	return CharactersN(r.Intn(3)+1) + seps[r.Intn(len(seps))] + Digits()
diff --git a/test/dates_test.go b/test/dates_test.go
index 3d72fbf..2c5c52d 100644
--- a/test/dates_test.go
+++ b/test/dates_test.go
@@ -2,7 +2,6 @@ package test
 
 import (
 	"testing"
-	"time"
 
 	"github.com/icrowley/fake"
 )
@@ -41,9 +40,8 @@ func TestDates(t *testing.T) {
 			t.Errorf("MonthNum failed with lang %s", lang)
 		}
 
-		n = fake.Year(50, 20)
-		year := time.Now().Year()
-		if n < year-50 || n > year+20 {
+		n = fake.Year(1950, 2020)
+		if n < 1950 || n > 2020 {
 			t.Errorf("Year failed with lang %s", lang)
 		}
 	}
diff --git a/test/general_test.go b/test/general_test.go
index 02ca5b7..bbdf74d 100644
--- a/test/general_test.go
+++ b/test/general_test.go
@@ -30,9 +30,9 @@ func TestGeneral(t *testing.T) {
 			t.Errorf("HexColor failed with lang %s", lang)
 		}
 
-		v = fake.ShortHexColor()
+		v = fake.HexColorShort()
 		if v == "" {
-			t.Errorf("ShortHexColor failed with lang %s", lang)
+			t.Errorf("HexColorShort failed with lang %s", lang)
 		}
 
 		v = fake.DigitsN(2)