dev-comments.txt

==============================================================================
------------------------------------------------------------------------------
Table of contents:
  Abstract......................................................|dev-comments|
  The setup function....................................|dev_comments.setup()|
  Configure the setup.............................|dev-comments-configuration|
  File modes.........................................|dev-comments-file-modes|
  Pre-filter modes.................................|dev-comments-filter-modes|
  Default mappings.............................|dev-comments-default-mappings|
  Default commands.............................|dev-comments-default-commands|
  Telecope integration................................|dev-comments-telescope|


------------------------------------------------------------------------------
                                                                  *dev-comments*
# Abstract~

*dev-comments.nvim* is a plugin that uses the tree-sitter-comment parser to
list and search for dev comments

Author: Omar Zeghouani
License: MIT


------------------------------------------------------------------------------
                                                          *dev_comments.setup()*
                         `dev_comments.setup`({config})
Module setup

Parameters~
{config} `(table|nil)` configuration options. See |dev-comments-configuration|

Usage~
`require("dev_comments").setup({})` (replace `{}` with your `config` table)

------------------------------------------------------------------------------
                                                    *dev-comments-configuration*
# Configuration~

Default values:
>
  {
    -- Enables vim.notify messages
    debug = false,
    -- Creates <Plug> mappings
    default_mappings = true,
    -- Create user commands
    default_commands = true,
    -- Each call of dev-comments is cached
    -- Play around with the reset autocommands for more aggressive caching
    cache = {
      enabled = true,
      reset_autocommands = { "BufWritePost", "BufWinEnter" },
    },
    -- Loads and sets default options for telescope plugin
    telescope = {
      load = true,
      -- See |dev-comments-file-modes|
      [Files.CURRENT] = {
        tags = {},
        users = {},
      },
      [Files.OPEN] = {
        tags = {},
        users = {},
      },
      [Files.ALL] = {
        hidden = false,
        tags = {},
        users = {},
      },
    },
    -- Cycle through dev-comments in a given buffer
    -- Caching is recommended for this feature
    cycle = {
      wrap = true,
    },
    -- Improves performance when searching in a large directory
    pre_filter = {
      -- See |dev-comments-filter-modes|
      command = FilterCommand.RIPGREP,
      -- If search fails, uses vim.loop.scan_dir (very slow)
      fallback_to_scan_dir = true,
    },
    -- Highlight for the tag in picker (not in buffer)
    highlight = {
      tags = {
        ["TODO"] = "TSWarning",
        ["HACK"] = "TSWarning",
        ["WARNING"] = "TSWarning",
        ["FIXME"] = "TSDanger",
        ["XXX"] = "TSDanger",
        ["BUG"] = "TSDanger",
      },
      -- Used if lookup fails for a given tag
      fallback = "TSNote",
    },
  }
<


==============================================================================
------------------------------------------------------------------------------
                                                                  *C.register()*
                                 `C.register`()
Return~
`(boolean)` Cache is registered

------------------------------------------------------------------------------
                                                                *C.unregister()*
                                `C.unregister`()
Return~
`(boolean)` Cache is unregistered


==============================================================================
------------------------------------------------------------------------------
Class~
{Opts} table of options used by comments.generate
Fields~
{files} `(string)`
{cwd} `(string)`
{hidden} `(boolean)`
{tags} `(string[])`
{users} `(string[])`
{find} `(string[])`

------------------------------------------------------------------------------
Class~
{Results} table of results returned by comments.generate
Fields~
{tag} `(string)`
{user} `(string)`
{range} Range
{bufnr} `(number)` Buffer number

------------------------------------------------------------------------------
Class~
{Range}
Fields~
{start_row} `(number)` The start row of text
{end_row} `(number)` The end row of text
{start_col} `(number)` The start column of text
{end_col} `(number)` The end column of text

------------------------------------------------------------------------------
                                                                  *C.generate()*
                         `C.generate`({files}, {opts})
Parameters~
{files} `(string)` # @see constants.Files
{opts} Opts
Return~
`(table)`


==============================================================================
------------------------------------------------------------------------------
                                                       *dev-comments-file-modes*
# File modes~

>
  {
    Files.CURRENT,
    Files.OPEN,
    Files.ALL
  }
<

------------------------------------------------------------------------------
                                                     *dev-comments-filter-modes*
# Pre-filter modes~

>
  {
    FilterCommand.RIPGREP,
    FilterCommand.GREP,
    FilterCommand.NONE,
  }
<


==============================================================================
------------------------------------------------------------------------------
                                                                 *C.goto_prev()*
                         `C.goto_prev`({wrap}, {opts})
Parameters~
{wrap} `(boolean)` Should wrap around
{opts} Opts

------------------------------------------------------------------------------
                                                                 *C.goto_next()*
                         `C.goto_next`({wrap}, {opts})
Parameters~
{wrap} `(boolean)` Should wrap around
{opts} Opts


==============================================================================
------------------------------------------------------------------------------
                                                                     *F.match()*
                  `F.match`({command}, {cwd}, {tags}, {users})
Parameters~
{command} `(string)` # @see constants.FilterCommand
{cwd} `(optional)` `(string)` # defaults to current working directory
{tags} `(optional)` `(string[])` # defaults to empty list
{users} `(optional)` `(string[])` # defaults to empty list
Return~
`(string[])` list of files with dev comments


==============================================================================
------------------------------------------------------------------------------
                                                 *dev-comments-default-mappings*

# Default mappings~

dev-comments.nvim comes with optional default mappings and commands

>
  function()
    -- <Plug> keymaps
    vim.keymap.set("n", "<Plug>DevCommentsTelescopeCurrent", function()
      require("telecope").extensions.dev_comments.current({})
    end, { silent = true })
    vim.keymap.set("n", "<Plug>DevCommentsTelescopeOpen", function()
      require("telecope").extensions.dev_comments.open({})
    end, { silent = true })
    vim.keymap.set("n", "<Plug>DevCommentsTelescopeAll", function()
      require("telecope").extensions.dev_comments.open({})
    end, { silent = true })
    vim.keymap.set("n", "<Plug>DevCommentsCyclePrev", function()
      require("dev_comments.cycle").goto_prev()
    end, { silent = true })
    vim.keymap.set("n", "<Plug>DevCommentsCycleNext", function()
      require("dev_comments.cycle").goto_next()
    end, { silent = true })

    -- Keybinds
    vim.keymap.set("n", "[c", "<Plug>DevCommentsCyclePrev")
    vim.keymap.set("n", "]c", "<Plug>DevCommentsCycleNext")
  end
<

------------------------------------------------------------------------------
                                                 *dev-comments-default-commands*

# Default commands~

>
  function()
    local Files = require("dev_comments.constants").Files
    local cache = require("dev_comments.cache")
    vim.api.nvim_create_user_command("DevCommentsCacheReset", function()
      cache.reset(Files.CURRENT)
      cache.reset(Files.OPEN)
      cache.reset(Files.ALL)
    end, {})
    vim.api.nvim_create_user_command("DevCommentsCacheToggle", function()
      local registered = cache.unregister()
      if not registered then cache.register() end
    end, {})
    vim.api.nvim_create_user_command("DevCommentsCacheDisable", function()
      cache.unregister()
    end, {})
    vim.api.nvim_create_user_command("DevCommentsCacheEnable", function()
      cache.register()
    end, {})
    vim.api.nvim_create_user_command("DevCommentsCyclePrev", function()
      require("dev_comments.cycle").goto_prev()
    end, {})
    vim.api.nvim_create_user_command("DevCommentsCycleNext", function()
      require("dev_comments.cycle").goto_next()
    end, {})
  end
<


==============================================================================
------------------------------------------------------------------------------
                                                        *dev-comments-telescope*

# Telescope~

dev-comments.nvim comes with first class telescope integration



 vim:tw=78:ts=8:noet:ft=help:norl: