Add some hints re. generating custom configuration output

It's not obvious that Symbol.config_string can be useful even when
generating other output formats, as it provides a hook for
_write_to_conf. Mention it in the 'config_string' documentation and in
relevant parts of the README.

2 files changed, 31 insertions, 5 deletions

diff --git a/README.rst b/README.rst
index dc3dc2c..a893434 100644
--- a/README.rst
+++ b/README.rst
@@ -129,6 +129,8 @@ Getting started
    Adding new configuration output formats should be relatively straightforward.
    See the implementation of ``write_config()`` in `kconfiglib.py
    <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib.py>`_.
+   The documentation for the ``Symbol.config_string`` property has some tips as
+   well.
    
 5. To update an old ``.config`` file after the Kconfig files have changed (e.g.
    to add new options), run ``oldconfig`` (prompts for values for new options)
@@ -642,9 +644,12 @@ Notes
   2, see `kconfiglib-2-changes.txt
   <https://github.com/ulfalizer/Kconfiglib/blob/master/kconfiglib-2-changes.txt>`_.
 
-* I sometimes see people add custom output formats, which is pretty straightforward to do (see the implementations of 
-  ``write_autoconf()`` and ``write_config()`` for a template). If you come up with something you think might
-  be useful to other people, I'm happy to take it in upstream. Batteries included and all that.
+* I sometimes see people add custom output formats, which is pretty
+  straightforward to do (see the implementations of ``write_autoconf()`` and
+  ``write_config()`` for a template, and also the documentation of the
+  ``Symbol.config_string`` property). If you come up with something you think
+  might be useful to other people, I'm happy to take it in upstream. Batteries
+  included and all that.
 
 * Kconfiglib assumes the modules symbol is ``MODULES``, which is backwards-compatible.
   A warning is printed by default if ``option modules`` is set on some other symbol.
diff --git a/kconfiglib.py b/kconfiglib.py
index 1af640e..b6c1d4a 100644
--- a/kconfiglib.py
+++ b/kconfiglib.py
@@ -3450,8 +3450,29 @@ class Symbol(object):
     config_string:
       The .config assignment string that would get written out for the symbol
       by Kconfig.write_config(). Returns the empty string if no .config
-      assignment would get written out. In general, visible symbols, symbols
-      with (active) defaults, and selected symbols get written out.
+      assignment would get written out.
+
+      In general, visible symbols, symbols with (active) defaults, and selected
+      symbols get written out. This includes all non-n-valued bool/tristate
+      symbols, and all visible string/int/hex symbols.
+
+      Symbols with the (no longer needed) 'option env=...' option generate no
+      configuration output, and neither does the special
+      'option defconfig_list' symbol.
+
+      Tip: This field is useful when generating custom configuration output,
+      even for non-.config-like formats. To write just the symbols that would
+      get written out to .config files, do this:
+
+        if sym.config_string:
+            *Write symbol, e.g. by looking sym.str_value*
+
+      This is a superset of the symbols written out by write_autoconf().
+      That function skips all n-valued symbols.
+
+      There usually won't be any great harm in just writing all symbols either,
+      though you might get some special symbols and possibly some "redundant"
+      n-valued symbol entries in there.
 
     nodes:
       A list of MenuNodes for this symbol. Will contain a single MenuNode for