From 5322aafc663cab6732bcf64523eb57d204255e49 Mon Sep 17 00:00:00 2001
From: Daniel Shimon <daniel.shimon22@gmail.com>
Date: Sun, 1 Aug 2021 00:37:54 +0300
Subject: [PATCH] Complete environment description (#4397)

* completers: env: Add env var's description

* news: Add complete-environment-description

* completers: env: Use generator

* completers: env: Show var type in display

* tests: completers: env: Update tests
---
 news/complete-environment-description.rst     | 23 +++++++++++++++++++
 .../completers/test_environment_completer.py  | 17 ++++++++++++--
 xonsh/completers/environment.py               | 13 +++++++++--
 3 files changed, 49 insertions(+), 4 deletions(-)
 create mode 100644 news/complete-environment-description.rst

diff --git a/news/complete-environment-description.rst b/news/complete-environment-description.rst
new file mode 100644
index 000000000..4695aa802
--- /dev/null
+++ b/news/complete-environment-description.rst
@@ -0,0 +1,23 @@
+**Added:**
+
+* Show environment variables' type and descriptions when completing them.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>
diff --git a/tests/completers/test_environment_completer.py b/tests/completers/test_environment_completer.py
index e873f5992..18044edc6 100644
--- a/tests/completers/test_environment_completer.py
+++ b/tests/completers/test_environment_completer.py
@@ -1,5 +1,6 @@
 import pytest
 
+from xonsh.environ import Env, Var
 from xonsh.parsers.completion_context import CompletionContextParser
 from xonsh.completers.environment import complete_environment_vars
 
@@ -18,7 +19,19 @@ def parser():
     ),
 )
 def test_simple(cmd, xession, monkeypatch, parser):
-    monkeypatch.setitem(xession.env, "WOW", 1)
+    monkeypatch.setattr(xession, "env", Env({"WOW": 1}))
 
     context = parser.parse(cmd, len(cmd))
-    assert complete_environment_vars(context) == ({"$WOW"}, 3)
+    comps, lprefix = complete_environment_vars(context)
+    assert lprefix == 3
+    assert set(comps) == {"$WOW"}
+
+
+def test_rich_completions(xession, monkeypatch, parser):
+    monkeypatch.setattr(xession, "env", Env({"WOW": 1}))
+    xession.env.register("WOW", type=int, doc="Nice Docs!")
+
+    context = parser.parse("$WO", 3)
+    completion = next(complete_environment_vars(context)[0])
+    assert completion.display == "$WOW [int]"
+    assert completion.description == "Nice Docs!"
diff --git a/xonsh/completers/environment.py b/xonsh/completers/environment.py
index c309e1968..516efe6a8 100644
--- a/xonsh/completers/environment.py
+++ b/xonsh/completers/environment.py
@@ -4,6 +4,7 @@ from xonsh.completers.tools import (
     contextual_completer,
     non_exclusive_completer,
     get_filter_function,
+    RichCompletion,
 )
 
 
@@ -25,6 +26,14 @@ def complete_environment_vars(context: CompletionContext):
     key = prefix[dollar_location + 1 :]
     lprefix = len(key) + 1
     filter_func = get_filter_function()
-    env_names = XSH.env
+    env = XSH.env
 
-    return {"$" + k for k in env_names if filter_func(k, key)}, lprefix
+    return (
+        RichCompletion(
+            "$" + k,
+            display=f"${k} [{type(v).__name__}]",
+            description=env.get_docs(k).doc,
+        )
+        for k, v in env.items()
+        if filter_func(k, key)
+    ), lprefix