diff --git a/oslo_config/generator.py b/oslo_config/generator.py
index 7b6e5ad4..1c1017f3 100644
--- a/oslo_config/generator.py
+++ b/oslo_config/generator.py
@@ -321,6 +321,14 @@ class _OptFormatter(object):
                 '# effect on stability and/or performance.\n'
             )
 
+        if opt.sample_default:
+            lines.append(
+                '#\n'
+                '# This option has a sample default set, which means that\n'
+                '# its actual default value may vary from the one documented\n'
+                '# below.\n'
+            )
+
         if hasattr(opt.type, 'format_defaults'):
             defaults = opt.type.format_defaults(opt.default,
                                                 opt.sample_default)
diff --git a/oslo_config/sphinxext.py b/oslo_config/sphinxext.py
index 00269310..00fdd038 100644
--- a/oslo_config/sphinxext.py
+++ b/oslo_config/sphinxext.py
@@ -146,6 +146,16 @@ def _format_opt(opt, group_name):
         yield _indent(
             'effect on stability and/or performance.', 6)
 
+    if opt.sample_default:
+        yield _indent(
+            '')
+        yield _indent(
+            'This option has a sample default set, which means that')
+        yield _indent(
+            'its actual default value may vary from the one documented')
+        yield _indent(
+            'above.')
+
     try:
         help_text = opt.help % {'default': 'the value above'}
     except (TypeError, KeyError, ValueError):
diff --git a/oslo_config/tests/test_generator.py b/oslo_config/tests/test_generator.py
index c966b40f..a7c5f4a3 100644
--- a/oslo_config/tests/test_generator.py
+++ b/oslo_config/tests/test_generator.py
@@ -803,6 +803,10 @@ class GeneratorTestCase(base.BaseTestCase):
 #
 
 # multiple strings (multi valued)
+#
+# This option has a sample default set, which means that
+# its actual default value may vary from the one documented
+# below.
 #multi_opt = 5
 #multi_opt = 6
 ''')),