From b33b157e1597112398200008cdb0d553fd14e7fe Mon Sep 17 00:00:00 2001
From: Brian Picciano <mediocregopher@gmail.com>
Date: Fri, 25 Jan 2019 16:46:39 -0500
Subject: [PATCH] mcfg: update docs to make running Populate more than once
 explicitly allowed

---
 mcfg/mcfg.go   |  4 +++-
 mcfg/source.go | 10 +++++++---
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/mcfg/mcfg.go b/mcfg/mcfg.go
index e63f5da..15bcb49 100644
--- a/mcfg/mcfg.go
+++ b/mcfg/mcfg.go
@@ -112,7 +112,9 @@ func populate(params []Param, src Source) error {
 }
 
 // Populate uses the Source to populate the values of all Params which were
-// added to the given mctx.Context, and all of its children.
+// added to the given mctx.Context, and all of its children. Populate may be
+// called multiple times with the same mctx.Context, each time will only affect
+// the values of the Params which were provided by the respective Source.
 //
 // Source may be nil to indicate that no configuration is provided. Only default
 // values will be used, and if any paramaters are required this will error.
diff --git a/mcfg/source.go b/mcfg/source.go
index 8c8717e..7f96842 100644
--- a/mcfg/source.go
+++ b/mcfg/source.go
@@ -12,9 +12,13 @@ type ParamValue struct {
 }
 
 // Source parses ParamValues out of a particular configuration source, given a
-// sorted set of possible Params to parse. The returned []ParamValue may contain
-// duplicates of the same Param's value. in which case the later value takes
-// precedence.
+// sorted set of possible Params to parse.
+//
+// Source should not return ParamValues which were not explicitly set to a value
+// by the configuration source.
+//
+// The returned []ParamValue may contain duplicates of the same Param's value.
+// in which case the later value takes precedence.
 type Source interface {
 	Parse([]Param) ([]ParamValue, error)
 }