diff --git a/include/spdk/bdev_module.h b/include/spdk/bdev_module.h
index a7106a467..39e571b53 100644
--- a/include/spdk/bdev_module.h
+++ b/include/spdk/bdev_module.h
@@ -91,8 +91,16 @@ struct spdk_bdev_module {
 	void (*config_text)(FILE *fp);
 
 	/**
-	 * Function called to return a text string representing the
-	 * module's configuration options for inclusion in a configuration file.
+	 * Function called to return a text string representing the module-level
+	 * JSON RPCs required to regenerate the current configuration.  This will
+	 * include module-level configuration options, or methods to construct
+	 * bdevs when one RPC may generate multiple bdevs (for example, an NVMe
+	 * controller with multiple namespaces).
+	 *
+	 * Per-bdev JSON RPCs (where one "construct" RPC always creates one bdev)
+	 * may be implemented here, or by the bdev's write_config_json function -
+	 * but not both.  Bdev module implementers may choose which mechanism to
+	 * use based on the module's design.
 	 *
 	 * \return 0 on success or Bdev specific negative error code.
 	 */
@@ -185,7 +193,14 @@ struct spdk_bdev_fn_table {
 	int (*dump_info_json)(void *ctx, struct spdk_json_write_ctx *w);
 
 	/**
-	 * Output bdev-specific configuration to a JSON stream. Optional - may be NULL.
+	 * Output bdev-specific RPC configuration to a JSON stream. Optional - may be NULL.
+	 *
+	 * This function should only be implemented for bdevs which can be configured
+	 * independently of other bdevs.  For example, RPCs to create a bdev for an NVMe
+	 * namespace may not be generated by this function, since enumerating an NVMe
+	 * namespace requires attaching to an NVMe controller, and that controller may
+	 * contain multiple namespaces.  The spdk_bdev_module's config_json function should
+	 * be used instead for these cases.
 	 *
 	 * The JSON write context will be initialized with an open object, so the bdev
 	 * driver should write all data necessary to recreate this bdev by invoking