Improve the docs of some configs

- Update the docs of the config: `kernel-vmmap`, `hexdump-group-use-big-endian`, `kernel_vmmap_via_pt`, and `resolve-heap-via-heuristic`

- Update the output of `get_show_string()` to display: ``See `help set <config>` for more information`` in the end of the output of `show <config>`

pwndbg/commands/heap.py

@@ -596,7 +596,7 @@ pwndbg.gdblib.config.add_param(
 pwndbg.gdblib.config.add_param(
     "default-visualize-chunk-number",
     10,
-    "the number of chunks to visualize (default is 10)",
+    "default number of chunks to visualize (default is 10)",
 )
 
 parser = argparse.ArgumentParser()

pwndbg/commands/hexdump.py

@@ -8,6 +8,7 @@ import pwndbg.gdblib.config
 import pwndbg.gdblib.memory
 import pwndbg.gdblib.regs
 import pwndbg.hexdump
+from pwndbg.color import message
 
 pwndbg.gdblib.config.add_param("hexdump-width", 16, "line width of hexdump command")
 pwndbg.gdblib.config.add_param("hexdump-bytes", 64, "number of bytes printed by hexdump command")
@@ -19,7 +20,8 @@ pwndbg.gdblib.config.add_param(
 pwndbg.gdblib.config.add_param(
     "hexdump-group-use-big-endian",
     False,
-    "Use big-endian within each group of bytes. Only applies to raw bytes, not the ASCII part. "
+    "whether to use big-endian within each group of bytes in hexdump command",
+    help_docstring="When `on`, use big-endian within each group of bytes. Only applies to raw bytes, not the ASCII part. "
     "See also hexdump-highlight-group-lsb.",
 )
 

pwndbg/gdblib/config.py

@@ -80,9 +80,11 @@ class Parameter(gdb.Parameter):
 
     def get_show_string(self, svalue):
         """Handles the GDB `show <param>` command"""
-        return "%s is %r." % (
+        more_information_hint = " See `help set %s` for more information." % self.param.name
+        return "%s is %r.%s" % (
             self.param.set_show_doc.capitalize(),
             svalue,
+            more_information_hint if self.__doc__ else "",
         )
 
     @staticmethod

pwndbg/gdblib/vmmap.py

@@ -36,13 +36,24 @@ custom_pages = []
 kernel_vmmap_via_pt = pwndbg.gdblib.config.add_param(
     "kernel-vmmap-via-page-tables",
     "deprecated",
-    "Deprecated in favor of `kernel-vmmap`",
+    "the deprecated config of the method get kernel vmmap",
+    help_docstring="Deprecated in favor of `kernel-vmmap`",
 )
 
 kernel_vmmap = pwndbg.gdblib.config.add_param(
     "kernel-vmmap",
     "page-tables",
-    "Can be set to 'page-tables' to use gdb-pt-dump for vmmap, 'monitor' to use 'monitor info mem', or 'none' to disable vmmap",
+    "the method to get vmmap information when debugging via QEMU kernel",
+    help_docstring="""\
+kernel-vmmap can be:
+page-tables    - read /proc/$qemu-pid/mem to parse kernel page tables to render vmmap
+monitor        - use QEMU's `monitor info mem` to render vmmap
+none           - disable vmmap rendering; useful if rendering is particularly slow
+
+Note that the page-tables method will require the QEMU kernel process to be on the same machine and within the same PID namespace. Running QEMU kernel and GDB in different Docker containers will not work. Consider running both containers with --pid=host (meaning they will see and so be able to interact with all processes on the machine).
+""",
+    param_class=gdb.PARAM_ENUM,
+    enum_sequence=["page-tables", "monitor", "none"],
 )
 
 
@@ -92,10 +103,6 @@ def get():
             pages.extend(kernel_vmmap_via_page_tables())
         elif kernel_vmmap == "monitor":
             pages.extend(kernel_vmmap_via_monitor_info_mem())
-        else:
-            # TODO: Properly validate the config option when it's set so we can
-            # remove this assert
-            assert kernel_vmmap == "none"
 
     if not pages and is_corefile():
         pages.extend(coredump_maps())

pwndbg/heap/__init__.py

@@ -40,14 +40,11 @@ resolve_heap_via_heuristic = add_heap_param(
     "resolve-heap-via-heuristic",
     "auto",
     "the strategy to resolve heap via heuristic",
-    help_docstring="""If pwndbg fails to use the debug symbols to resolve the heap, it can try to resolve the heap via heuristics.
-This configuration sets the strategy for resolving the heap.
-
-There are three strategies:
-auto    == pwndbg will try to use heuristics if debug symbols are missing
-force   == pwndbg will always try to use heuristics, even if debug symbols are available
-never   == pwndbg will never use heuristics to resolve the heap
-
+    help_docstring="""\
+resolve-heap-via-heuristic can be:
+auto    - pwndbg will try to use heuristics if debug symbols are missing
+force   - pwndbg will always try to use heuristics, even if debug symbols are available
+never   - pwndbg will never use heuristics to resolve the heap
 
 If the output of the heap related command produces errors with heuristics, you can try manually setting the libc symbol addresses.
 For this, see the `heap_config` command output and set the `main_arena`, `mp_`, `global_max_fast`, `tcache` and `thread_arena` addresses.

tests/gdb-tests/tests/test_gdblib_parameter.py

@@ -49,7 +49,10 @@ def test_gdb_parameter_default_value_works(start_binary, params):
     pwndbg.gdblib.config_mod.Parameter(param)
 
     out = gdb.execute(f"show {param_name}", to_string=True)
-    assert out == f"{set_show_doc.capitalize()} is {displayed_value!r}.\n"
+    assert (
+        out
+        == f"{set_show_doc.capitalize()} is {displayed_value!r}. See `help set {param_name}` for more information.\n"
+    )
     if (
         optional_kwargs.get("param_class") in (gdb.PARAM_UINTEGER, gdb.PARAM_INTEGER)
         and default_value == 0