docs: improving documentation around when to use config methods

Based on PR feedback - be clearer about how the configuration methods overlap and what their best use cases are.

Author: davidjoy

docs/decisions/0007-javascript-file-configuration.rst

@@ -113,7 +113,7 @@ JavaScript file configuration is compatible with runtime MFE configuration.
 frontend-platform loads configuration in a predictable order:
 
 - environment variable config
-- optional handlers (used to merge MFE-specific config in via additional
+- optional handlers (commonly used to merge MFE-specific config in via additional
   process.env variables)
 - JS file config
 - runtime config
@@ -125,7 +125,6 @@ In the future if we deprecate environment variable config, it's likely that
 we keep both JS file config and runtime configuration around.  JS file config
 primarily to handle extensibility, and runtime config for everything else.
 
-
 Rejected Alternatives
 ---------------------
 

src/config.js

@@ -2,10 +2,27 @@
  * #### Import members from **@edx/frontend-platform**
  *
  * The configuration module provides utilities for working with an application's configuration
- * document (ConfigDocument).  Configuration environment variables can be supplied to the
- * application in four different ways:
+ * document (ConfigDocument).  Configuration variables can be supplied to the
+ * application in four different ways.  They are applied in the following order:
  *
- * ##### Build-time Environment Variables
+ * - Build-time Configuration
+ *   - Environment Variables
+ *   - JavaScript File
+ * - Runtime Configuration
+ *
+ * Last one in wins.  Variables with the same name defined via the later methods will override any
+ * defined using an earlier method.  i.e., if a variable is defined in Runtime Configuration, that
+ * will override the same variable defined in either Build-time Configuration method (environment
+ * variables or JS file).  Configuration defined in a JS file will override environment variables.
+ *
+ * ##### Build-time Configuration
+ *
+ * Build-time configuration methods add config variables into the app when it is built by webpack.
+ * This saves the app an API call and means it has all the information it needs to initialize right
+ * away.  There are two methods of supplying build-time configuration: environment variables and a
+ * JavaScript file.
+ *
+ * ######Environment Variables
  *
  * A set list of required config variables can be supplied as
  * command-line environment variables during the build process.
@@ -19,12 +36,23 @@
  * Note that additional variables _cannot_ be supplied via this method without using the `config`
  * initialization handler.  The app won't pick them up and they'll appear `undefined`.
  *
- * ##### JavaScript File Configuration
+ * This configuration method is being deprecated in favor of JavaScript File Configuration.
  *
- * Configuration variables can be supplied in an optional file
- * named env.config.js.  This file must export either an Object containing configuration variables
- * or a function.  The function must return an Object containing configuration variables or,
- * alternately, a promise which resolves to an Object.
+ * ###### JavaScript File Configuration
+ *
+ * Configuration variables can be supplied in an optional file named env.config.js.  This file must
+ * export either an Object containing configuration variables or a function.  The function must
+ * return an Object containing configuration variables or, alternately, a promise which resolves to
+ * an Object.
+ *
+ * Using a function or async function allows the configuration to be resolved at runtime (because
+ * the function will be executed at runtime).  This is not common, and the capability is included
+ * for the sake of flexibility.
+ *
+ * JavaScript File Configuration is well-suited to extensibility use cases or component overrides,
+ * in that the configuration file can depend on any installed JavaScript module.  It is also the
+ * preferred way of doing build-time configuration if runtime configuration isn't used by your
+ * deployment of the platform.
  *
  * Exporting a config object:
  * ```
@@ -59,15 +87,20 @@
  *
  * ##### Runtime Configuration
  *
- * Configuration variables can also be supplied using the "runtime
- * configuration" method, taking advantage of the Micro-frontend Config API in edx-platform.
- * More information on this API can be found in the ADR which introduced it:
+ * Configuration variables can also be supplied using the "runtime configuration" method, taking
+ * advantage of the Micro-frontend Config API in edx-platform. More information on this API can be
+ * found in the ADR which introduced it:
  *
  * https://github.com/openedx/edx-platform/blob/master/lms/djangoapps/mfe_config_api/docs/decisions/0001-mfe-config-api.rst
  *
  * The runtime configuration method can be enabled by supplying a MFE_CONFIG_API_URL via one of the other
  * two configuration methods above.
  *
+ * Runtime configuration is particularly useful if you need to supply different configurations to
+ * a single deployment of a micro-frontend, for instance.  It is also a perfectly valid alternative
+ * to build-time configuration, though it introduces an additional API call to edx-platform on MFE
+ * initialization.
+ *
  * ##### Initialization Config Handler
  *
  * The configuration document can be extended by