From 41978198d72f84492e84fc8f736c679e8570b1da Mon Sep 17 00:00:00 2001
From: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Date: Sat, 23 Jun 2018 10:51:39 +0200
Subject: [PATCH] genrest: Mention implicit default values

It's common for people to put in a 'default n' "just in case", because
it might not be obvious that bool symbols implicitly default to 'n'. To
make it clearer, mention the implicit default value on the reference
pages of symbols without defaults.

Also mention that choices without defaults default to the first
(visible) symbol in the choice.

Note: Adding to the confusion, Kconfig used to generate a
'# CONFIG_FOO is not set' line for 'default n', but no output when there
was no default. I changed that recently in both the C tools and
Kconfiglib. There's no output either case now (unless the symbol is
visible).

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
---
 doc/scripts/genrest.py | 27 +++++++++++++++++++++------
 1 file changed, 21 insertions(+), 6 deletions(-)

diff --git a/doc/scripts/genrest.py b/doc/scripts/genrest.py
index 2d6473cfef0e3..d8a2e78ae5f36 100644
--- a/doc/scripts/genrest.py
+++ b/doc/scripts/genrest.py
@@ -209,17 +209,32 @@ def defaults_rst(sc):
     # Returns RST that lists the 'default' properties of 'sc' (symbol or
     # choice)
 
-    if not sc.defaults:
+    if isinstance(sc, kconfiglib.Symbol) and sc.choice:
+        # 'default's on choice symbols have no effect (and generate a warning).
+        # The implicit value hint below would be misleading as well.
         return ""
 
     rst = "Defaults\n" \
           "========\n\n"
 
-    for value, cond in sc.defaults:
-        default_str = kconfiglib.expr_str(value)
-        if cond is not sc.kconfig.y:
-            default_str += " if " + kconfiglib.expr_str(cond)
-        rst += "- {}\n".format(default_str)
+    if sc.defaults:
+        for value, cond in sc.defaults:
+            rst += "- " + kconfiglib.expr_str(value)
+            if cond is not sc.kconfig.y:
+                rst += " if " + kconfiglib.expr_str(cond)
+            rst += "\n"
+
+    else:
+        rst += "No defaults. Implicitly defaults to "
+
+        if isinstance(sc, kconfiglib.Choice):
+            rst += "the first (visible) choice option.\n"
+        elif sc.orig_type in (kconfiglib.BOOL, kconfiglib.TRISTATE):
+            rst += "``n``.\n"
+        else:
+            # This is accurate even for int/hex symbols, though an active
+            # 'range' might clamp the value (which is then treated as zero)
+            rst += "the empty string.\n"
 
     return rst + "\n"