diff --git a/src/main/java/com/google/devtools/common/options/OptionsUsage.java b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
index 633b6f6..61829e2 100644
--- a/src/main/java/com/google/devtools/common/options/OptionsUsage.java
+++ b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
@@ -56,6 +56,8 @@
     StringBuilder out = new StringBuilder();
     String sep = "";
     for (String paragraph : NEWLINE_SPLITTER.split(in)) {
+      // TODO(ccalvarin) break iterators expect hyphenated words to be line-breakable, which looks
+      // funny for --flag
       BreakIterator boundary = BreakIterator.getLineInstance(); // (factory)
       boundary.setText(paragraph);
       out.append(sep).append(indentString);
@@ -132,18 +134,27 @@
       return;
     }
     if (!annotation.help().equals("")) {
-      usage.append(paragraphFill(annotation.help(), 4, 80)); // (indent, width)
+      usage.append(paragraphFill(annotation.help(), /*indent=*/ 4, /*width=*/ 80));
       usage.append('\n');
     }
     ImmutableList<String> expansion = getExpansionIfKnown(optionField, optionsData);
     if (expansion == null) {
-      usage.append("    Expands to unknown options.\n");
+      usage.append(paragraphFill("Expands to unknown options.", /*indent=*/ 6, /*width=*/ 80));
+      usage.append('\n');
     } else if (!expansion.isEmpty()) {
       StringBuilder expandsMsg = new StringBuilder("Expands to: ");
       for (String exp : expansion) {
         expandsMsg.append(exp).append(" ");
       }
-      usage.append(paragraphFill(expandsMsg.toString(), 4, 80)); // (indent, width)
+      usage.append(paragraphFill(expandsMsg.toString(), /*indent=*/ 6, /*width=*/ 80));
+      usage.append('\n');
+    }
+    if (annotation.implicitRequirements().length > 0) {
+      StringBuilder requiredMsg = new StringBuilder("Using this option will also add: ");
+      for (String req : annotation.implicitRequirements()) {
+        requiredMsg.append(req).append(" ");
+      }
+      usage.append(paragraphFill(requiredMsg.toString(), /*indent=*/ 6, /*width=*/ 80));
       usage.append('\n');
     }
   }
@@ -187,7 +198,7 @@
     usage.append("</dt>\n");
     usage.append("<dd>\n");
     if (!annotation.help().isEmpty()) {
-      usage.append(paragraphFill(escaper.escape(annotation.help()), 0, 80)); // (indent, width)
+      usage.append(paragraphFill(escaper.escape(annotation.help()), /*indent=*/ 0, /*width=*/ 80));
       usage.append('\n');
     }
     ImmutableList<String> expansion = getExpansionIfKnown(optionField, optionsData);
@@ -203,7 +214,7 @@
             .append(escaper.escape(exp))
             .append("</code><br/>\n");
       }
-      usage.append(expandsMsg.toString()); // (indent, width)
+      usage.append(expandsMsg.toString());
       usage.append('\n');
     }
     usage.append("</dd>\n");
diff --git a/src/test/java/com/google/devtools/common/options/OptionsParserTest.java b/src/test/java/com/google/devtools/common/options/OptionsParserTest.java
index e1aa563..01084ab 100644
--- a/src/test/java/com/google/devtools/common/options/OptionsParserTest.java
+++ b/src/test/java/com/google/devtools/common/options/OptionsParserTest.java
@@ -1121,8 +1121,8 @@
     OptionsParser parser = OptionsParser.newOptionsParser(ExpansionOptions.class);
     String usage =
         parser.describeOptions(ImmutableMap.<String, String>of(), OptionsParser.HelpVerbosity.LONG);
-    assertThat(usage).contains("  --expands\n    Expands to: --underlying=from_expansion");
-    assertThat(usage).contains("  --expands_by_function\n    Expands to: --expands");
+    assertThat(usage).contains("  --expands\n      Expands to: --underlying=from_expansion");
+    assertThat(usage).contains("  --expands_by_function\n      Expands to: --expands");
   }
 
   @Test
diff --git a/src/test/java/com/google/devtools/common/options/OptionsTest.java b/src/test/java/com/google/devtools/common/options/OptionsTest.java
index e8d7237..32f257b 100644
--- a/src/test/java/com/google/devtools/common/options/OptionsTest.java
+++ b/src/test/java/com/google/devtools/common/options/OptionsTest.java
@@ -18,12 +18,9 @@
 import static java.util.Arrays.asList;
 import static org.junit.Assert.fail;
 
-import com.google.common.collect.ImmutableList;
 import com.google.common.testing.EqualsTester;
 import java.net.MalformedURLException;
 import java.net.URL;
-import java.util.Map;
-import java.util.TreeSet;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
@@ -85,79 +82,6 @@
       expansion = {"--host=special.google.com", "--port=8080"}
     )
     public Void special;
-
-    // Interestingly, the class needs to be public, or else the default constructor ends up not
-    // being public and the expander can't be instantiated.
-    /**
-     * Defines an expansion function that looks at other options defined with it and expands to
-     * options that match a pattern.
-     */
-    public static class ExpansionDependsOnOtherOptionDefinitions implements ExpansionFunction {
-      @Override
-      public ImmutableList<String> getExpansion(ExpansionContext context) {
-        TreeSet<String> flags = new TreeSet<>();
-        for (Map.Entry<String, ?> entry : context.getOptionsData().getAllNamedFields()) {
-          if (entry.getKey().startsWith("specialexp_")) {
-            flags.add("--" + entry.getKey());
-          }
-        }
-        return ImmutableList.copyOf(flags);
-      }
-    }
-
-    /**
-     * Defines an expansion function that adapts its expansion to the value assigned to the original
-     * expansion option.
-     */
-    public static class ExpansionDependsOnFlagValue implements ExpansionFunction {
-      @Override
-      public ImmutableList<String> getExpansion(ExpansionContext context)
-          throws OptionsParsingException {
-        String value = context.getUnparsedValue();
-        if (value == null) {
-          throw new ExpansionNeedsValueException("Expansion value not set.");
-        }
-        if (value.equals("foo_bar")) {
-          return ImmutableList.<String>of("--specialexp_foo", "--specialexp_bar");
-        }
-
-        throw new OptionsParsingException("Unexpected expansion argument: " + value);
-      }
-    }
-
-    @Option(
-      name = "specialexp_foo",
-      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
-      effectTags = {OptionEffectTag.NO_OP},
-      defaultValue = "false"
-    )
-    public boolean specialExpFoo;
-
-    @Option(
-      name = "specialexp_bar",
-      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
-      effectTags = {OptionEffectTag.NO_OP},
-      defaultValue = "false"
-    )
-    public boolean specialExpBar;
-
-    @Option(
-      name = "specialexp",
-      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
-      effectTags = {OptionEffectTag.NO_OP},
-      defaultValue = "null",
-      expansionFunction = ExpansionDependsOnOtherOptionDefinitions.class
-    )
-    public Void specialExp;
-
-    @Option(
-      name = "dynamicexp",
-      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
-      effectTags = {OptionEffectTag.NO_OP},
-      defaultValue = "null",
-      expansionFunction = ExpansionDependsOnFlagValue.class
-    )
-    public Void variableExpansion;
   }
 
   @Test
@@ -423,13 +347,10 @@
   }
 
   @Test
-  public void usageForExpansion() {
+  public void usageForStaticExpansion() {
     String usage = Options.getUsage(HttpOptions.class);
     assertThat(usage)
-        .contains("  --special\n    Expands to: --host=special.google.com --port=8080");
-    // Expect that the usage text contains the expansion appropriate to the options bases that were
-    // loaded into the options parser.
-    assertThat(usage).contains("  --specialexp\n    Expands to: --specialexp_bar --specialexp_foo");
+        .contains("  --special\n      Expands to: --host=special.google.com --port=8080");
   }
 
   public static class NullTestOptions extends OptionsBase {
@@ -462,7 +383,7 @@
                 + "    The URL at which the server will be running.");
     assertThat(usage)
         .contains(
-            "  --none\n" + "    An expanded option.\n" + "    Expands to: --host=www.google.com");
+            "  --none\n" + "    An expanded option.\n" + "      Expands to: --host=www.google.com");
   }
 
   public static class MyURLConverter implements Converter<URL> {
@@ -622,26 +543,38 @@
   }
 
   @Test
-  public void expansionFunction() throws Exception {
-    Options<HttpOptions> options1 = Options.parse(HttpOptions.class, new String[] {"--specialexp"});
-    Options<HttpOptions> options2 =
-        Options.parse(HttpOptions.class, new String[] {"--specialexp_foo", "--specialexp_bar"});
-    assertThat(options1.getOptions()).isEqualTo(options2.getOptions());
+  public void usageForExpansionFunction() {
+    // Expect that the usage text contains the expansion appropriate to the options bases that were
+    // loaded into the options parser.
+    String usage = Options.getUsage(TestOptions.class);
+    assertThat(usage)
+        .contains(
+            "  --prefix_expansion\n"
+                + "    Expands to all options with a specific prefix.\n"
+                + "      Expands to: --specialexp_bar --specialexp_foo");
   }
 
   @Test
+  public void expansionFunction() throws Exception {
+    Options<TestOptions> options1 =
+        Options.parse(TestOptions.class, new String[] {"--prefix_expansion"});
+    Options<TestOptions> options2 =
+        Options.parse(TestOptions.class, new String[] {"--specialexp_foo", "--specialexp_bar"});
+    assertThat(options1.getOptions()).isEqualTo(options2.getOptions());
+  }
+  @Test
   public void dynamicExpansionFunctionWorks() throws Exception {
-    Options<HttpOptions> options1 =
-        Options.parse(HttpOptions.class, new String[] {"--dynamicexp=foo_bar"});
-    Options<HttpOptions> options2 =
-        Options.parse(HttpOptions.class, new String[] {"--specialexp_foo", "--specialexp_bar"});
+    Options<TestOptions> options1 =
+        Options.parse(TestOptions.class, new String[] {"--dynamicexp=foo_bar"});
+    Options<TestOptions> options2 =
+        Options.parse(TestOptions.class, new String[] {"--specialexp_foo", "--specialexp_bar"});
     assertThat(options1.getOptions()).isEqualTo(options2.getOptions());
   }
 
   @Test
   public void dynamicExpansionFunctionUnknowValue() throws Exception {
     try {
-      Options.parse(HttpOptions.class, new String[] {"--dynamicexp=foo"});
+      Options.parse(TestOptions.class, new String[] {"--dynamicexp=foo"});
       fail("Unknown expansion argument should cause a failure.");
     } catch (OptionsParsingException e) {
       assertThat(e).hasMessage("Unexpected expansion argument: foo");
diff --git a/src/test/java/com/google/devtools/common/options/OptionsUsageTest.java b/src/test/java/com/google/devtools/common/options/OptionsUsageTest.java
new file mode 100644
index 0000000..c720163
--- /dev/null
+++ b/src/test/java/com/google/devtools/common/options/OptionsUsageTest.java
@@ -0,0 +1,247 @@
+// Copyright 2017 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.common.options;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.devtools.common.options.OptionsParser.HelpVerbosity;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit test for {@link OptionsUsage}. */
+@RunWith(JUnit4.class)
+public final class OptionsUsageTest {
+
+  private OptionsData data;
+
+  @Before
+  public void setUp() {
+    data = OptionsParser.getOptionsDataInternal(TestOptions.class);
+  }
+
+  private String getUsage(String fieldName, HelpVerbosity verbosity) {
+    StringBuilder builder = new StringBuilder();
+    OptionsUsage.getUsage(data.getFieldFromName(fieldName), builder, verbosity, data);
+    return builder.toString();
+  }
+
+  @Test
+  public void stringValue_short() {
+    assertThat(getUsage("test_string", HelpVerbosity.SHORT)).isEqualTo("  --test_string\n");
+  }
+
+  @Test
+  public void stringValue_medium() {
+    assertThat(getUsage("test_string", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --test_string (a string; default: \"test string default\")\n");
+  }
+
+  @Test
+  public void stringValue_long() {
+    assertThat(getUsage("test_string", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_string (a string; default: \"test string default\")\n"
+                + "    a string-valued option to test simple option operations\n");
+  }
+
+  @Test
+  public void intValue_short() {
+    assertThat(getUsage("expanded_c", HelpVerbosity.SHORT)).isEqualTo("  --expanded_c\n");
+  }
+
+  @Test
+  public void intValue_medium() {
+    assertThat(getUsage("expanded_c", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --expanded_c (an integer; default: \"12\")\n");
+  }
+
+  @Test
+  public void intValue_long() {
+    assertThat(getUsage("expanded_c", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --expanded_c (an integer; default: \"12\")\n"
+                + "    an int-value'd flag used to test expansion logic\n");
+  }
+
+  @Test
+  public void multipleValue_short() {
+    assertThat(getUsage("test_multiple_string", HelpVerbosity.SHORT))
+        .isEqualTo("  --test_multiple_string\n");
+  }
+
+  @Test
+  public void multipleValue_medium() {
+    assertThat(getUsage("test_multiple_string", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --test_multiple_string (a string; may be used multiple times)\n");
+  }
+
+  @Test
+  public void multipleValue_long() {
+    assertThat(getUsage("test_multiple_string", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_multiple_string (a string; may be used multiple times)\n"
+                + "    a repeatable string-valued flag with its own unhelpful help text\n");
+  }
+
+  @Test
+  public void customConverterValue_short() {
+    assertThat(getUsage("test_list_converters", HelpVerbosity.SHORT))
+        .isEqualTo("  --test_list_converters\n");
+  }
+
+  @Test
+  public void customConverterValue_medium() {
+    assertThat(getUsage("test_list_converters", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --test_list_converters (a list of strings; may be used multiple times)\n");
+  }
+
+  @Test
+  public void customConverterValue_long() {
+    assertThat(getUsage("test_list_converters", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_list_converters (a list of strings; may be used multiple times)\n"
+                + "    a repeatable flag that accepts lists, but doesn't want to have lists of \n"
+                + "    lists as a final type\n");
+  }
+
+  @Test
+  public void staticExpansionOption_short() {
+    assertThat(getUsage("test_expansion", HelpVerbosity.SHORT)).isEqualTo("  --test_expansion\n");
+  }
+
+  @Test
+  public void staticExpansionOption_medium() {
+    assertThat(getUsage("test_expansion", HelpVerbosity.MEDIUM)).isEqualTo("  --test_expansion\n");
+  }
+
+  @Test
+  public void staticExpansionOption_long() {
+    assertThat(getUsage("test_expansion", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_expansion\n"
+                + "    this expands to an alphabet soup.\n"
+                + "      Expands to: --noexpanded_a --expanded_b=false --expanded_c 42 --\n"
+                + "      expanded_d bar \n");
+  }
+
+  @Test
+  public void recursiveExpansionOption_short() {
+    assertThat(getUsage("test_recursive_expansion_top_level", HelpVerbosity.SHORT))
+        .isEqualTo("  --test_recursive_expansion_top_level\n");
+  }
+
+  @Test
+  public void recursiveExpansionOption_medium() {
+    assertThat(getUsage("test_recursive_expansion_top_level", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --test_recursive_expansion_top_level\n");
+  }
+
+  @Test
+  public void recursiveExpansionOption_long() {
+    assertThat(getUsage("test_recursive_expansion_top_level", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_recursive_expansion_top_level\n"
+                + "    Lets the children do all the work.\n"
+                + "      Expands to: --test_recursive_expansion_middle1 --\n"
+                + "      test_recursive_expansion_middle2 \n");
+  }
+
+  @Test
+  public void expansionToMultipleValue_short() {
+    assertThat(getUsage("test_expansion_to_repeatable", HelpVerbosity.SHORT))
+        .isEqualTo("  --test_expansion_to_repeatable\n");
+  }
+
+  @Test
+  public void expansionToMultipleValue_medium() {
+    assertThat(getUsage("test_expansion_to_repeatable", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --test_expansion_to_repeatable\n");
+  }
+
+  @Test
+  public void expansionToMultipleValue_long() {
+    assertThat(getUsage("test_expansion_to_repeatable", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_expansion_to_repeatable\n"
+                + "    Go forth and multiply, they said.\n"
+                + "      Expands to: --test_multiple_string=expandedFirstValue --\n"
+                + "      test_multiple_string=expandedSecondValue \n");
+  }
+
+  @Test
+  public void implicitRequirementOption_short() {
+    assertThat(getUsage("test_implicit_requirement", HelpVerbosity.SHORT))
+        .isEqualTo("  --test_implicit_requirement\n");
+  }
+
+  @Test
+  public void implicitRequirementOption_medium() {
+    assertThat(getUsage("test_implicit_requirement", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --test_implicit_requirement (a string; default: \"direct implicit\")\n");
+  }
+
+  @Test
+  public void implicitRequirementOption_long() {
+    assertThat(getUsage("test_implicit_requirement", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_implicit_requirement (a string; default: \"direct implicit\")\n"
+                + "    this option really needs that other one, isolation of purpose has failed.\n"
+                + "      Using this option will also add: --implicit_requirement_a=implicit \n"
+                + "      requirement, required \n");
+  }
+
+  @Test
+  public void expansionFunctionOptionThatReadsUserValue_short() {
+    assertThat(getUsage("test_expansion_function", HelpVerbosity.SHORT))
+        .isEqualTo("  --test_expansion_function\n");
+  }
+
+  @Test
+  public void expansionFunctionOptionThatReadsUserValue_medium() {
+    assertThat(getUsage("test_expansion_function", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --test_expansion_function\n");
+  }
+
+  @Test
+  public void expansionFunctionOptionThatReadsUserValue_long() {
+    assertThat(getUsage("test_expansion_function", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --test_expansion_function\n"
+                + "    this is for testing expansion-by-function functionality.\n"
+                + "      Expands to unknown options.\n");
+  }
+
+  @Test
+  public void expansionFunctionOptionThatExpandsBasedOnOtherLoadedOptions_short() {
+    assertThat(getUsage("prefix_expansion", HelpVerbosity.SHORT))
+        .isEqualTo("  --prefix_expansion\n");
+  }
+
+  @Test
+  public void expansionFunctionOptionThatExpandsBasedOnOtherLoadedOptions_medium() {
+    assertThat(getUsage("prefix_expansion", HelpVerbosity.MEDIUM))
+        .isEqualTo("  --prefix_expansion\n");
+  }
+
+  @Test
+  public void expansionFunctionOptionThatExpandsBasedOnOtherLoadedOptions_long() {
+    assertThat(getUsage("prefix_expansion", HelpVerbosity.LONG))
+        .isEqualTo(
+            "  --prefix_expansion\n"
+                + "    Expands to all options with a specific prefix.\n"
+                + "      Expands to: --specialexp_bar --specialexp_foo \n");
+  }
+}
diff --git a/src/test/java/com/google/devtools/common/options/TestOptions.java b/src/test/java/com/google/devtools/common/options/TestOptions.java
index 7dc0228..4fa0309 100644
--- a/src/test/java/com/google/devtools/common/options/TestOptions.java
+++ b/src/test/java/com/google/devtools/common/options/TestOptions.java
@@ -16,6 +16,8 @@
 import com.google.common.collect.ImmutableList;
 import com.google.devtools.common.options.InvocationPolicyEnforcerTestBase.ToListConverter;
 import java.util.List;
+import java.util.Map;
+import java.util.TreeSet;
 
 /** Options for testing. */
 public class TestOptions extends OptionsBase {
@@ -30,7 +32,8 @@
     name = "test_string",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.NO_OP},
-    defaultValue = TEST_STRING_DEFAULT
+    defaultValue = TEST_STRING_DEFAULT,
+    help = "a string-valued option to test simple option operations"
   )
   public String testString;
 
@@ -43,7 +46,8 @@
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.NO_OP},
     defaultValue = "", // default value is ignored when allowMultiple=true.
-    allowMultiple = true
+    allowMultiple = true,
+    help = "a repeatable string-valued flag with its own unhelpful help text"
   )
   public List<String> testMultipleString;
 
@@ -57,7 +61,10 @@
     effectTags = {OptionEffectTag.NO_OP},
     defaultValue = "",
     allowMultiple = true,
-    converter = ToListConverter.class
+    converter = ToListConverter.class,
+    help =
+        "a repeatable flag that accepts lists, but doesn't want to have lists of lists "
+            + "as a final type"
   )
   public List<String> testListConverters;
 
@@ -82,7 +89,8 @@
       "42",
       "--expanded_d",
       "bar"
-    }
+    },
+    help = "this expands to an alphabet soup."
   )
   public Void testExpansion;
 
@@ -99,7 +107,8 @@
     expansion = {
       "--test_recursive_expansion_middle1",
       "--test_recursive_expansion_middle2",
-    }
+    },
+    help = "Lets the children do all the work."
   )
   public Void testRecursiveExpansionTopLevel;
 
@@ -153,7 +162,8 @@
     name = "expanded_c",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.NO_OP},
-    defaultValue = "12"
+    defaultValue = "12",
+    help = "an int-value'd flag used to test expansion logic"
   )
   public int expandedC;
 
@@ -182,7 +192,8 @@
     expansion = {
       "--test_multiple_string=expandedFirstValue",
       "--test_multiple_string=expandedSecondValue"
-    }
+    },
+    help = "Go forth and multiply, they said."
   )
   public Void testExpansionToRepeatable;
 
@@ -198,7 +209,8 @@
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.NO_OP},
     defaultValue = TEST_IMPLICIT_REQUIREMENT_DEFAULT,
-    implicitRequirements = {"--implicit_requirement_a=" + IMPLICIT_REQUIREMENT_A_REQUIRED}
+    implicitRequirements = {"--implicit_requirement_a=" + IMPLICIT_REQUIREMENT_A_REQUIRED},
+    help = "this option really needs that other one, isolation of purpose has failed."
   )
   public String testImplicitRequirement;
 
@@ -227,6 +239,10 @@
   public static final String TEST_EXPANSION_FUNCTION_ACCEPTED_VALUE = "valueA";
   public static final String EXPANDED_D_EXPANSION_FUNCTION_VALUE = "expanded valueA";
 
+  /*
+   * Expansion function flags
+   */
+
   /** Used for testing an expansion flag that requires a value. */
   public static class TestExpansionFunction implements ExpansionFunction {
     @Override
@@ -248,7 +264,8 @@
     defaultValue = "null",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.NO_OP},
-    expansionFunction = TestExpansionFunction.class
+    expansionFunction = TestExpansionFunction.class,
+    help = "this is for testing expansion-by-function functionality."
   )
   public Void testExpansionFunction;
 
@@ -270,4 +287,79 @@
     expansionFunction = TestVoidExpansionFunction.class
   )
   public Void testVoidExpansionFunction;
+
+  // Interestingly, the class needs to be public, or else the default constructor ends up not
+  // being public and the expander can't be instantiated.
+  /**
+   * Defines an expansion function that looks at other options defined with it and expands to
+   * options that match a pattern.
+   */
+  public static class ExpansionDependsOnOtherOptionDefinitions implements ExpansionFunction {
+    @Override
+    public ImmutableList<String> getExpansion(ExpansionContext context) {
+      TreeSet<String> flags = new TreeSet<>();
+      for (Map.Entry<String, ?> entry : context.getOptionsData().getAllNamedFields()) {
+        if (entry.getKey().startsWith("specialexp_")) {
+          flags.add("--" + entry.getKey());
+        }
+      }
+      return ImmutableList.copyOf(flags);
+    }
+  }
+
+  @Option(
+    name = "prefix_expansion",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.NO_OP},
+    defaultValue = "null",
+    expansionFunction = ExpansionDependsOnOtherOptionDefinitions.class,
+    help = "Expands to all options with a specific prefix."
+  )
+  public Void specialExp;
+
+  /**
+   * Defines an expansion function that adapts its expansion to the value assigned to the original
+   * expansion option.
+   */
+  public static class ExpansionDependsOnFlagValue implements ExpansionFunction {
+    @Override
+    public ImmutableList<String> getExpansion(ExpansionContext context)
+        throws OptionsParsingException {
+      String value = context.getUnparsedValue();
+      if (value == null) {
+        throw new ExpansionNeedsValueException("Expansion value not set.");
+      }
+      if (value.equals("foo_bar")) {
+        return ImmutableList.<String>of("--specialexp_foo", "--specialexp_bar");
+      }
+
+      throw new OptionsParsingException("Unexpected expansion argument: " + value);
+    }
+  }
+
+  @Option(
+    name = "dynamicexp",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.NO_OP},
+    defaultValue = "null",
+    expansionFunction = ExpansionDependsOnFlagValue.class,
+    help = "Expands depending on the value provided."
+  )
+  public Void variableExpansion;
+
+  @Option(
+    name = "specialexp_foo",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.NO_OP},
+    defaultValue = "false"
+  )
+  public boolean specialExpFoo;
+
+  @Option(
+    name = "specialexp_bar",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.NO_OP},
+    defaultValue = "false"
+  )
+  public boolean specialExpBar;
 }