leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix some spelling & grammar (#1475)

Browse Source
This commit is contained in:
Chris A James
2021-11-20 10:03:52 +00:00
committed by GitHub
parent d686fb2799
commit 7493f51700
2 changed files with 26 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CONTRIBUTING.md
View File

@@ -6,7 +6,7 @@ Thanks for taking the time to submit code to Telescope if you're reading this! W
## Documentation with treesitter ## Documentation with treesitter
We are generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation that is part of the returning module will be exported. So example: We are generating docs based on the tree sitter syntax tree. TJ wrote a grammar that includes the documentation in this syntax tree so we can do take this function header documentation and transform it into vim documentation. All documentation that is part of the returning module will be exported. For example:
```lua ```lua
local m = {} local m = {}
@@ -37,7 +37,7 @@ This guide contains all annotations and we will update it when we add new annota
## What is missing? ## What is missing?
The docgen has some problems on which people can work. This would happen in https://github.com/tjdevries/tree-sitter-lua and documentation of some modules here. The docgen has some problems on which people can work. This would happen in [https://github.com/tjdevries/tree-sitter-lua](https://github.com/tjdevries/tree-sitter-lua) and documentation of some modules here.
I would suggest we are documenting lua/telescope/builtin/init.lua rather than the files itself. We can use that init.lua file as "header" file, so we are not cluttering the other files. I would suggest we are documenting lua/telescope/builtin/init.lua rather than the files itself. We can use that init.lua file as "header" file, so we are not cluttering the other files.
How to help out with documentation: How to help out with documentation:

48
developers.md
View File

@@ -31,9 +31,9 @@ programming language. If not then you can find information for Lua here:
## Guide to your first Picker ## Guide to your first Picker
To guide you along the way to first picker we will do the following. We will To guide you along the way to your first picker we will open an empty lua
open an empty lua scratch file in which we will develop the picker and run it scratch file, in which we will develop the picker and run it each time using
each time using `:luafile %`. Later this file then be bundled as extension. `:luafile %`. Later we will bundle this file as an extension.
### Requires ### Requires
@@ -44,9 +44,9 @@ local finders = require "telescope.finders"
local conf = require("telescope.config").values local conf = require("telescope.config").values
``` ```
- `pickers` is the main module which is used to create a new picker. - `pickers`: main module which is used to create a new picker.
- `finders` provides interfaces to fill the picker with items. - `finders`: provides interfaces to fill the picker with items.
- `config` the `values` table holds the user configuration. - `config`: `values` table which holds the user's configuration.
So to make it easier we access this table directly in `conf`. So to make it easier we access this table directly in `conf`.
### First Picker ### First Picker
@@ -71,15 +71,15 @@ colors()
``` ```
Running this code with `:luafile %` should open a telescope picker with the entries `red`, Running this code with `:luafile %` should open a telescope picker with the entries `red`,
`green`, `blue`. Selecting a color and pressing enter will open a new file, in this case `green`, `blue`. Selecting a color and pressing enter will open a new file. In this case
it's not what we want so we will address this after explaining this snippet. it's not what we want, so we will address this after explaining this snippet.
We will define a new function `colors` which accepts a table `opts`. This is good We will define a new function `colors` which accepts a table `opts`. This is good
practice because now the user can change how telescope behaves by passing in their practice because now the user can change how telescope behaves by passing in their
own `opts` table when calling `colors`. own `opts` table when calling `colors`.
For example the user can pass in a configuration in `opts` which allows them to change For example the user can pass in a configuration in `opts` which allows them to change
the theme used for the picker. To allow this we have to make sure we pass the `opts` table the theme used for the picker. To allow this, we make sure to pass the `opts` table
as the first argument to `pickers.new`. The second argument is a table as the first argument to `pickers.new`. The second argument is a table
which defines the default behavior of the picker. which defines the default behavior of the picker.
@@ -109,7 +109,7 @@ picker.
### Replacing Actions ### Replacing Actions
Now calling `colors()` will result in the opening of telescope with the values. Now calling `colors()` will result in the opening of telescope with the values:
`red`, `green` and `blue`. The default theme isn't optimal for this picker so we `red`, `green` and `blue`. The default theme isn't optimal for this picker so we
want to change it and thanks to the acceptance of `opts` we can. We will replace want to change it and thanks to the acceptance of `opts` we can. We will replace
the last line with the following to open the picker with the `dropdown` theme. the last line with the following to open the picker with the `dropdown` theme.
@@ -120,7 +120,7 @@ colors(require("telescope.themes").get_dropdown{})
Now let's address the issue that selecting a color opens a new buffer. For that Now let's address the issue that selecting a color opens a new buffer. For that
we need to replace the default select action. The benefit of replacing rather than we need to replace the default select action. The benefit of replacing rather than
mapping a new function to `<CR>` is that it will respect user configuration. So mapping a new function to `<CR>` is that it will respect the user's configuration. So
if a user has remapped `select_default` to another key then this decision will if a user has remapped `select_default` to another key then this decision will
be respected and it works as expected for the user. be respected and it works as expected for the user.
@@ -131,11 +131,11 @@ local actions = require "telescope.actions"
local action_state = require "telescope.actions.state" local action_state = require "telescope.actions.state"
``` ```
- `actions` holds all actions that can be mapped by a user and we need it to - `actions`: holds all actions that can be mapped by a user. We also need it to
access the default action so we can replace it. Also see `:help access the default action so we can replace it. Also see `:help
telescope.actions` telescope.actions`
- `action_state` gives us a few utility functions we can use to get the - `action_state`: gives us a few utility functions we can use to get the
current picker, current selection or current line. Also see `:help current picker, current selection or current line. Also see `:help
telescope.actions.state` telescope.actions.state`
@@ -177,7 +177,7 @@ closed.
You can look at the selection with `print(vim.inspect(selection))` and see that it differs from our input You can look at the selection with `print(vim.inspect(selection))` and see that it differs from our input
(string), this is because internally we pack it into a table with different (string), this is because internally we pack it into a table with different
keys. You can specify this behavior and wel'l talk about that in the next keys. You can specify this behavior and we'll talk about that in the next
section. Now all that is left is to do something with the selection we have. In section. Now all that is left is to do something with the selection we have. In
this case we just put the text in the current buffer with `vim.api.nvim_put`. this case we just put the text in the current buffer with `vim.api.nvim_put`.
@@ -211,8 +211,8 @@ more interesting. We will end up with the following new code for `finders.new_ta
}, },
``` ```
With the new snippet we no longer have an array of strings but an array of With the new snippet, we no longer have an array of strings but an array of
tables. Each table has a color name and the color's hex value. tables. Each table has a color, name, and the color's hex value.
`entry_maker` is a function that will receive each table and then we can set the `entry_maker` is a function that will receive each table and then we can set the
values we need. It's best practice to have a `value` reference to the values we need. It's best practice to have a `value` reference to the
@@ -223,9 +223,9 @@ The `display` key is required and is either a string or a `function(tbl)`,
where `tbl` is the table returned by `entry_maker`. So in this example `tbl` would where `tbl` is the table returned by `entry_maker`. So in this example `tbl` would
give our `display` function access to `value` and `ordinal`. give our `display` function access to `value` and `ordinal`.
If our picker will have a lot lot of values it's suggested to use a function for `display` If our picker will have a lot of values it's suggested to use a function for `display`,
especially if you are modifying the text to display. This way the function will only be executed especially if you are modifying the text to display. This way the function will only be executed
for the entries being displayed. For an examples of an entry maker take a look at for the entries being displayed. For an example of an entry maker take a look at
`lua/telescope/make_entry.lua`. `lua/telescope/make_entry.lua`.
A good way to make your `display` more like a table is to use a `displayer` which can be found in A good way to make your `display` more like a table is to use a `displayer` which can be found in
@@ -237,9 +237,9 @@ this allows us to have different display and sorting values. This allows `displa
to be more complex with icons and special indicators but `ordinal` could be a simpler to be more complex with icons and special indicators but `ordinal` could be a simpler
sorting key. sorting key.
There are other important keys which can be set but do not make sense in the There are other important keys which can be set, but do not make sense in the
current context as we are not dealing wiht files: current context as we are not dealing with files:
- `path`: to set the absolute path of the file to make sure its always found - `path`: to set the absolute path of the file to make sure it's always found
- `lnum`: to specify a line number in the file. This will allow the - `lnum`: to specify a line number in the file. This will allow the
`conf.grep_previewer` to show that line and the default action to jump to `conf.grep_previewer` to show that line and the default action to jump to
that line. that line.
@@ -264,15 +264,15 @@ finder = finders.new_oneshot_job { "find", opts },
### More examples ### More examples
A good way to find more examples is to look into the `lua/telescope/builtin/` A good way to find more examples is to look into the [lua/telescope/builtin](https://github.com/nvim-telescope/telescope.nvim/tree/master/lua/telescope/builtin)
directory which contains all of the builtin pickers. Another way to find more examples directory which contains all of the builtin pickers. Another way to find more examples
is to take a look at the [extension wiki page](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions) is to take a look at the [extension wiki page](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions)
as this provides many extensions peopel have already written which use these concepts. as this provides many extensions people have already written which use these concepts.
If you still have any questions after reading this guide please feel free to ask us for If you still have any questions after reading this guide please feel free to ask us for
more information on [gitter](https://gitter.im/nvim-telescope/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) more information on [gitter](https://gitter.im/nvim-telescope/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
and we will happily answer your questions and hopefully allow us to improve this guide. You can also and we will happily answer your questions and hopefully allow us to improve this guide. You can also
help us to improve this guide by sending a PRs. help us to improve this guide by sending a PR.
## Technical ## Technical