Improve the 'referenced' docstring

 - Point out why dependencies from surrounding if's and menus are
   included

 - Clarify that .referenced isn't transitive. Only "direct" references
   are included.

 - Give a hint about direct dependencies and expr_items()

Prompted by https://github.com/ulfalizer/Kconfiglib/issues/69.

1 files changed, 26 insertions, 2 deletions

diff --git a/kconfiglib.py b/kconfiglib.py
index bfcefec..e31b4c8 100644
--- a/kconfiglib.py
+++ b/kconfiglib.py
@@ -3857,9 +3857,31 @@ class Symbol(object):
       A set() with all symbols and choices referenced in the properties and
       property conditions of the symbol.
 
-      Also includes dependencies inherited from surrounding menus and if's.
+      Also includes dependencies from surrounding menus and if's, because those
+      get propagated to the symbol (see the 'Intro to symbol values' section in
+      the module docstring).
+
       Choices appear in the dependencies of choice symbols.
 
+      For the following definitions, only B and not C appears in A's
+      'referenced'. To get transitive references, you'll have to recursively
+      expand 'references' until no new items appear.
+
+        config A
+                bool
+                depends on B
+
+        config B
+                bool
+                depends on C
+
+        config C
+                bool
+
+      See the Symbol.direct_dep attribute if you're only interested in the
+      direct dependencies of the symbol (its 'depends on'). You can extract the
+      symbols in it with the global expr_items() function.
+
     env_var:
       If the Symbol has an 'option env="FOO"' option, this contains the name
       ("FOO") of the environment variable. None for symbols without no
@@ -4729,7 +4751,9 @@ class Choice(object):
       A set() with all symbols referenced in the properties and property
       conditions of the choice.
 
-      Also includes dependencies inherited from surrounding menus and if's.
+      Also includes dependencies from surrounding menus and if's, because those
+      get propagated to the choice (see the 'Intro to symbol values' section in
+      the module docstring).
 
     is_optional:
       True if the choice has the 'optional' flag set on it and can be in