Merge remote-tracking branch upstream-master into master

am: 9d2aa11004

Change-Id: Idc6b70ef72f260b65d9bb7b126f2af059a53e906

1 files changed, 7 insertions, 5 deletions

diff --git a/java/com/google/devtools/common/options/OptionsProvider.java b/java/com/google/devtools/common/options/OptionsProvider.java
index d467fe5..ece5d5d 100644
--- a/java/com/google/devtools/common/options/OptionsProvider.java
+++ b/java/com/google/devtools/common/options/OptionsProvider.java
@@ -73,11 +73,13 @@ public interface OptionsProvider extends OptionsClassProvider {
   List<OptionValueDescription> asListOfOptionValues();
 
   /**
-   * Canonicalizes the list of options that this OptionsParser has parsed. The
-   * contract is that if the returned set of options is passed to an options
-   * parser with the same options classes, then that will have the same effect
-   * as using the original args (which are passed in here), except for cosmetic
-   * differences.
+   * Canonicalizes the list of options that this OptionsParser has parsed.
+   *
+   * <p>The contract is that if the returned set of options is passed to an options parser with the
+   * same options classes, then that will have the same effect as using the original args (which are
+   * passed in here), except for cosmetic differences. We do not guarantee that the 'canonical' list
+   * is unique, since some flags may have effects unknown to the parser (--config, for Bazel), so we
+   * do not reorder flags to further simplify the list.
    */
   List<String> canonicalize();
 }