diff --git a/pkgs/applications/editors/neovim/utils.nix b/pkgs/applications/editors/neovim/utils.nix
index b72e758d26e1..76c40a08fc91 100644
--- a/pkgs/applications/editors/neovim/utils.nix
+++ b/pkgs/applications/editors/neovim/utils.nix
@@ -38,7 +38,7 @@ let
     , plugins ? []
     # forwarded to configure.customRC
     , customRC ? ""
-    # same values as in vimUtils.vimrcContent
+    # same values as in vimUtils.vimrcContent (deprecated)
     , configure ? { }
 
     # for forward compability, when adding new environments, haskell etc.
diff --git a/pkgs/applications/editors/vim/plugins/vim-utils.nix b/pkgs/applications/editors/vim/plugins/vim-utils.nix
index 4d2742b42418..288a9408d2f8 100644
--- a/pkgs/applications/editors/vim/plugins/vim-utils.nix
+++ b/pkgs/applications/editors/vim/plugins/vim-utils.nix
@@ -165,7 +165,11 @@ let
 
   rtpPath = ".";
 
-  # Generates a packpath folder as expected by vim
+  /* Generates a packpath folder as expected by vim
+       Example:
+       packDir (myVimPackage.{ start = [ vimPlugins.vim-fugitive ]; opt = [] })
+       => "/nix/store/xxxxx-pack-dir"
+  */
   packDir = packages:
   let
     linkVimlPlugin = plugin: packageName: dir: ''
@@ -233,7 +237,7 @@ let
   vimrcContent = {
     packages ? null,
     vam ? null,
-    pathogen ? null,
+    pathogen ? null, # deprecated
     plug ? null,
     beforePlugins ? ''
       " configuration generated by NIX
@@ -255,23 +259,7 @@ let
         call plug#end()
       '';
 
-      /*
-       vim-addon-manager = VAM
-
-       * maps names to plugin location
-
-       * manipulates &rtp at startup time
-         or when Vim has been running for a while
-
-       * can activate plugins laziy (eg when loading a specific filetype)
-
-       * knows about vim plugin dependencies (addon-info.json files)
-
-       * still is minimalistic (only loads one file), the "check out" code it also
-         has only gets loaded when a plugin is requested which is not found on disk
-         yet
-
-      */
+     # vim-addon-manager = VAM (deprecated)
       vamImpl =
       let
         knownPlugins = vam.knownPlugins or vimPlugins;