Repository: neovim/neovim
File: src/nvim/api/vim.c (C)

Code before:
/// connected to an external process. Instead, input sent on the channel
/// will be echoed directly by the terminal. This is useful to display
/// ANSI terminal sequences returned as part of an RPC message, or similar.
///
/// Note: to directly initiate the terminal using the right size, display the
/// buffer in a configured window before calling this. For instance, for a
/// floating display, first create an empty buffer using |nvim_create_buf()|,
/// then display it using |nvim_open_win()|, and then  call this function.
/// Then |nvim_chan_send()| can be called immediately to process sequences
/// in a virtual terminal having the intended size.
///
/// Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
/// can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
/// [terminal-scrollback-pager]()
///
/// ```lua
/// vim.api.nvim_create_user_command('TermHl', function()
///   local b = vim.api.nvim_create_buf(false, true)
///   local chan = vim.api.nvim_open_term(b, {})
///   vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n'))
///   vim.api.nvim_win_set_buf(0, b)
/// end, { desc = 'Highlights ANSI termcodes in curbuf' })
/// ```
///
/// @param buffer Buffer to use. If non-empty, the contents will be written
///               to the PTY.
/// @param opts   Optional parameters.
///          - on_input: Lua callback for input sent, i e keypresses in terminal
///            mode. Note: keypresses are sent raw as they would be to the pty
///            master end. For instance, a carriage return is sent
///            as a "\r", not as a "\n". |textlock| applies. It is possible
///            to call |nvim_chan_send()| directly in the callback however.
///                 `["input", term, bufnr, data]`
///          - force_crlf: (boolean, default true) Convert "\n" to "\r\n".
/// @param[out] err Error details, if any
/// @return Channel id, or 0 on error
Integer nvim_open_term(Buffer buffer, Dict(open_term) *opts, Error *err)
  FUNC_API_SINCE(7)
  FUNC_API_TEXTLOCK_ALLOW_CMDWIN
{
  buf_T *buf = find_buffer_by_handle(buffer, err);
  if (!buf) {
    return 0;
  }

  if (buf == cmdwin_buf) {
    api_set_error(err, kErrorTypeException, "%s", e_cmdwin);
    return 0;
  }

  LuaRef cb = LUA_NOREF;

Review comment (suggestion):
```suggestion
/// @param buffer Buffer to use. Buffer contents (if any) will be written
///               to the PTY.
```

Code after:
/// connected to an external process. Instead, input sent on the channel
/// will be echoed directly by the terminal. This is useful to display
/// ANSI terminal sequences returned as part of an RPC message, or similar.
///
/// Note: to directly initiate the terminal using the right size, display the
/// buffer in a configured window before calling this. For instance, for a
/// floating display, first create an empty buffer using |nvim_create_buf()|,
/// then display it using |nvim_open_win()|, and then  call this function.
/// Then |nvim_chan_send()| can be called immediately to process sequences
/// in a virtual terminal having the intended size.
///
/// Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
/// can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
/// [terminal-scrollback-pager]()
///
/// ```lua
/// vim.api.nvim_create_user_command('TermHl', function()
///   local b = vim.api.nvim_create_buf(false, true)
///   local chan = vim.api.nvim_open_term(b, {})
///   vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n'))
///   vim.api.nvim_win_set_buf(0, b)
/// end, { desc = 'Highlights ANSI termcodes in curbuf' })
/// ```
///
/// @param buffer Buffer to use. Buffer contents (if any) will be written
///               to the PTY.
/// @param opts   Optional parameters.
///          - on_input: Lua callback for input sent, i e keypresses in terminal
///            mode. Note: keypresses are sent raw as they would be to the pty
///            master end. For instance, a carriage return is sent
///            as a "\r", not as a "\n". |textlock| applies. It is possible
///            to call |nvim_chan_send()| directly in the callback however.
///                 `["input", term, bufnr, data]`
///          - force_crlf: (boolean, default true) Convert "\n" to "\r\n".
/// @param[out] err Error details, if any
/// @return Channel id, or 0 on error
Integer nvim_open_term(Buffer buffer, Dict(open_term) *opts, Error *err)
  FUNC_API_SINCE(7)
  FUNC_API_TEXTLOCK_ALLOW_CMDWIN
{
  buf_T *buf = find_buffer_by_handle(buffer, err);
  if (!buf) {
    return 0;
  }

  if (buf == cmdwin_buf) {
    api_set_error(err, kErrorTypeException, "%s", e_cmdwin);
    return 0;
  }

  LuaRef cb = LUA_NOREF;