add basic documentation

envconf.go

@@ -19,6 +19,9 @@ type Config struct {
     env map[string]cEntry
 }
 
+// NewConfig returns an envconf.Config that is used to read configuration from environment variables.
+// The environment variables are stored in envconf.Config, so changes to the environment after NewConfig has been called
+// will not be taken into account.
 func NewConfig()(*Config) {
     config := new(Config)
     config.parsed = false
@@ -40,6 +43,8 @@ func NewConfig()(*Config) {
     return config
 }
 
+// Define defines the type of an environment variable.
+// Variables without a defined type will be ignored by Parse.
 func (c *Config) Define(key string, dtype DataType) {
     upper := strings.ToUpper(key)
     entry, ok := c.env[upper]
@@ -55,6 +60,8 @@ func (c *Config) Define(key string, dtype DataType) {
     }
 }
 
+// DefineDefault defines the type and default value of an environment variable.
+// Variables without a defined type will be ignored by Parse.
 func (c *Config) DefineDefault(key string, val string, dtype DataType) {
     upper := strings.ToUpper(key)
     entry, ok := c.env[upper]
@@ -75,6 +82,8 @@ func (c *Config) DefineDefault(key string, val string, dtype DataType) {
     }
 }
 
+// Parse parses the environment variables previously defined by Define and DefineDefault.
+// Parse should only be called once for a given envconf.Config.
 func (c *Config) Parse() {
     if c.parsed {
         return
@@ -93,6 +102,10 @@ func (c *Config) Parse() {
     }
 }
 
+// Status prints out failures that occured while parsing the environment to os.Stderr.
+// Variables that have been defined without a default value and are
+// missing from the environment will be considered a failure.
+// If parsing of any of the variables has failed Status will return false.
 func (c *Config) Status()(ok bool) {
     ok = c.parsed
     if ok {
@@ -100,7 +113,7 @@ func (c *Config) Status()(ok bool) {
             err := v.parsed.err
             if err != nil {
                 ok = false
-                fmt.Println(err)
+                fmt.Frintln(os.Stderr, err)
             }
         }
     }
@@ -119,26 +132,47 @@ func (c *Config) getRaw(key string, dtype DataType)(val cValue) {
     return
 }
 
+// GetInt returns the value of an environment variable.
+// If the variable is not defined as envconf.TypeInt the function will return 0.
 func (c *Config) GetInt(key string)(int64) {
     val := c.getRaw(key, TypeInt)
     return val.intval
 }
+
+// GetMetric returns the value of an environment variable.
+// If the variable is not defined as envconf.TypeMetric the function will return 0.
 func (c *Config) GetMetric(key string)(int64) {
     val := c.getRaw(key, TypeMetric)
     return val.intval
 }
+
+// GetDirectory returns the value of an environment variable.
+// If the variable is not defined as envconf.TypeDirectory the
+// function will return the empty string.
 func (c *Config) GetDirectory(key string)(string) {
     val := c.getRaw(key, TypeDirectory)
     return val.strval
 }
+
+// GetString returns the value of an environment variable.
+// If the variable is not defined as envconf.TypeString the
+// function will return the empty string.
 func (c *Config) GetString(key string)(string) {
     val := c.getRaw(key, TypeString)
     return val.strval
 }
+
+// GetDuration returns the value of an environment variable.
+// If the variable is not defined as envconf.TypeDuration the
+// function will return time.Duration(0).
 func (c *Config) GetDuration(key string)(time.Duration) {
     val := c.getRaw(key, TypeDuration)
     return val.durval
 }
+
+// GetBool returns the value of an environment variable.
+// If the variable is not defined as envconf.TypeBool the
+// function will return false.
 func (c *Config) GetBool(key string)(bool) {
     val := c.getRaw(key, TypeBool)
     return val.boolval