feat: add toggle_doc functionality (#1647)

* feat: Add toggle_doc functionality

fix: Update docs view on entry change

* Replace toggle logic by open/close

* add docs and pinned flags

* add faq for disabling docs

* chore(git): ignore .DS_Store

---------

Co-authored-by: hrsh7th <629908+hrsh7th@users.noreply.github.com>

.gitignore

@@ -1,3 +1,4 @@
 doc/tags
 utils/stylua
+.DS_Store
 

doc/cmp.txt

@@ -155,6 +155,9 @@ NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functio
 *cmp.visible* ()
   Return a boolean showing whether the completion menu is visible or not.
 
+*cmp.visible_docs* ()
+  Return a boolean showing whether the docs window is visible or not.
+
 *cmp.get_entries* ()
   Return all current entries.
 
@@ -197,6 +200,11 @@ NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functio
     }
   }
 <
+*cmp.open_docs* ()
+  Open docs view.
+
+*cmp.close_docs* ()
+  Close docs view.
 
 *cmp.scroll_docs* (delta: number)
   Scroll the documentation window if visible.
@@ -335,6 +343,12 @@ There are also builtin mapping helper functions you can use:
   *cmp.mapping.select_prev_item* (option: { behavior = cmp.SelectBehavior, count = 1 })
     Same as |cmp.select_prev_item|.
 
+  *cmp.mapping.open_docs* ()
+    Same as |cmp.open_docs|.
+
+  *cmp.mapping.close_docs* ()
+    Same as |cmp.close_docs|.
+
   *cmp.mapping.scroll_docs* (delta: number)
     Same as |cmp.scroll_docs|.
 
@@ -659,6 +673,12 @@ view~
   The view class used to customize nvim-cmp's appearance.
   Currently available configuration options are:
 
+                                                *cmp-config.view.docs.auto_open*
+view.docs.auto_open~
+  `boolean`
+
+  Specify whether to show the docs_view when selecting an item.
+
                            *cmp-config.window.{completion,documentation}.border*
 window.{completion,documentation}.border~
   `string | string[] | nil`
@@ -900,6 +920,38 @@ How to disable commitCharacters?~
   }
 <
 
+How to disable automatic display of docs view?~
+
+  You can add the `view.docs.auto_open = false` for configuration.
+>lua
+  cmp.setup {
+    ...
+    view = {
+      docs = {
+        auto_open = false
+      }
+    }
+    ...
+  }
+<
+
+  additionaly, if you want to open/close docs view via your key mapping, you
+  can define keymapping as the following.
+>lua
+  cmp.setup {
+    ...
+    mapping = {
+      ['<C-g>'] = function()
+        if cmp.visible_docs() then
+          cmp.close_docs()
+        else
+          cmp.open_docs()
+        end
+      end
+    }
+    ...
+  }
+<
 
 How to disable auto-completion?~
 How to use nvim-cmp as omnifunc?~

lua/cmp/config/default.lua

@@ -95,6 +95,9 @@ return function()
         name = 'custom',
         selection_order = 'top_down',
       },
+      docs = {
+        auto_open = true,
+      }
     },
 
     window = {

lua/cmp/config/mapping.lua

@@ -178,6 +178,24 @@ mapping.scroll_docs = function(delta)
   end
 end
 
+--- Opens the documentation window.
+mapping.open_docs = function()
+  return function(fallback)
+    if not require('cmp').open_docs() then
+      fallback()
+    end
+  end
+end
+
+--- Close the documentation window.
+mapping.close_docs = function()
+  return function(fallback)
+    if not require('cmp').close_docs() then
+      fallback()
+    end
+  end
+end
+
 ---Select next completion item.
 mapping.select_next_item = function(option)
   return function(fallback)

lua/cmp/init.lua

@@ -181,6 +181,31 @@ cmp.scroll_docs = cmp.sync(function(delta)
   end
 end)
 
+---Whether the documentation window is visible or not.
+cmp.visible_docs = cmp.sync(function()
+  return cmp.core.view.docs_view:visible()
+end)
+
+---Opens the documentation window.
+cmp.open_docs = cmp.sync(function()
+  if not cmp.visible_docs() then
+    cmp.core.view:open_docs()
+    return true
+  else
+    return false
+  end
+end)
+
+---Closes the documentation window.
+cmp.close_docs = cmp.sync(function()
+  if cmp.visible_docs() then
+    cmp.core.view:close_docs()
+    return true
+  else
+    return false
+  end
+end)
+
 ---Confirm completion
 cmp.confirm = cmp.sync(function(option, callback)
   option = option or {}

lua/cmp/types/cmp.lua

@@ -168,19 +168,23 @@ cmp.ItemField = {
 ---@field public entry_filter nil|function(entry: cmp.Entry, ctx: cmp.Context): boolean
 
 ---@class cmp.ViewConfig
----@field public entries cmp.EntriesConfig
+---@field public entries cmp.EntriesViewConfig
+---@field public docs cmp.DocsViewConfig
 
----@alias cmp.EntriesConfig cmp.CustomEntriesConfig|cmp.NativeEntriesConfig|cmp.WildmenuEntriesConfig|string
+---@alias cmp.EntriesViewConfig cmp.CustomEntriesViewConfig|cmp.NativeEntriesViewConfig|cmp.WildmenuEntriesViewConfig|string
 
----@class cmp.CustomEntriesConfig
+---@class cmp.CustomEntriesViewConfig
 ---@field name 'custom'
 ---@field selection_order 'top_down'|'near_cursor'
 
----@class cmp.NativeEntriesConfig
+---@class cmp.NativeEntriesViewConfig
 ---@field name 'native'
 
----@class cmp.WildmenuEntriesConfig
+---@class cmp.WildmenuEntriesViewConfig
 ---@field name 'wildmenu'
 ---@field separator string|nil
 
+---@class cmp.DocsViewConfig
+---@field public auto_open boolean
+
 return cmp

lua/cmp/view.lua

@@ -10,6 +10,7 @@ local ghost_text_view = require('cmp.view.ghost_text_view')
 
 ---@class cmp.View
 ---@field public event cmp.Event
+---@field private is_docs_view_pinned boolean
 ---@field private resolve_dedup cmp.AsyncDedup
 ---@field private native_entries_view cmp.NativeEntriesView
 ---@field private custom_entries_view cmp.CustomEntriesView
@@ -23,6 +24,7 @@ local view = {}
 view.new = function()
   local self = setmetatable({}, { __index = view })
   self.resolve_dedup = async.dedup()
+  self.is_docs_view_pinned = false
   self.custom_entries_view = custom_entries_view.new()
   self.native_entries_view = native_entries_view.new()
   self.wildmenu_entries_view = wildmenu_entries_view.new()
@@ -128,6 +130,7 @@ end
 ---Close menu
 view.close = function(self)
   if self:visible() then
+    self.is_docs_view_pinned = false
     self.event:emit('complete_done', {
       entry = self:_get_entries_view():get_selected_entry(),
     })
@@ -142,6 +145,9 @@ end
 
 ---Abort menu
 view.abort = function(self)
+  if self:visible() then
+    self.is_docs_view_pinned = false
+  end
   self:_get_entries_view():abort()
   self.docs_view:close()
   self.ghost_text_view:hide()
@@ -156,6 +162,28 @@ view.visible = function(self)
   return self:_get_entries_view():visible()
 end
 
+---Opens the documentation window.
+view.open_docs = function(self)
+  self.is_docs_view_pinned = true
+  local e = self:get_selected_entry()
+  if e then
+    e:resolve(vim.schedule_wrap(self.resolve_dedup(function()
+      if not self:visible() then
+        return
+      end
+      self.docs_view:open(e, self:_get_entries_view():info())
+    end)))
+  end
+end
+
+---Closes the documentation window.
+view.close_docs = function(self)
+  self.is_docs_view_pinned = false
+  if self:get_selected_entry() then
+    self.docs_view:close()
+  end
+end
+
 ---Scroll documentation window if possible.
 ---@param delta integer
 view.scroll_docs = function(self, delta)
@@ -239,7 +267,9 @@ view.on_entry_change = async.throttle(function(self)
       if not self:visible() then
         return
       end
+      if self.is_docs_view_pinned or config.get().view.docs.auto_open then
         self.docs_view:open(e, self:_get_entries_view():info())
+      end
     end)))
   else
     self.docs_view:close()