Skip to content
This repository was archived by the owner on Aug 15, 2025. It is now read-only.
This repository was archived by the owner on Aug 15, 2025. It is now read-only.

Vim: -doc """Text""". not parsed correctly for non-stdlib code #1578

Closed
Closed
Vim: -doc """Text""". not parsed correctly for non-stdlib code#1578
Labels
bugSomething isn't working
@S0AndS0

Description

@S0AndS0
S0AndS0
opened on Jan 28, 2025

Describe the bug

Documentation text does not show up when working on Erlang files, but do show for built-in code.

To Reproduce

  1. Install Arch, or other Linux distribution; I use Arch BTW™
  2. Install Vim, not NeoVim, ex sudo pacman -S gvim
  3. Install YouCompleteMe Vim plugin for LSP client stuff, for example via junegunn/vim-plug plug-in manager that'd look a bit like; 
    call plug#begin('~/.vim/plugged')
  let g:plug_timeout = 300

  Plug 'ycm-core/YouCompleteMe', { 'do': 'CXX=$(which g++) ./install.py --clang-completer --cs-completer --go-completer --java-completer --rust-completer --ts-completer' }
call plug#end()
  4. Use patch from ycm-core/lsp-examples PR#44 to install Erlang LS. Which in pure Bash, I.E. without any Python wrapping, might look something like; 
    ## Install Erlang LS dependencies
sudo pacman -S erlang &&
  yay -S rebar3;

## Clone and compile Erlang LS
_erlang_ls_dir="${HOME}/git/hub/erlang-ls";

mkdir -vp "${_erlang_ls_dir}";

git clone "https://github.com/erlang-ls/erlang_ls" &&
  cd "${_//*\/}" &&
  make;

## Add YouCompleteMe client configuration pointing at results of make
tee -a "${HOME}/.vimrc" 1>/dev/null <<EOF
let g:ycm_language_server += [
  \   {
  \     'name': 'erlang',
  \     'filetypes': [ 'erlang' ],
  \     'cmdline': [  expand( g:ycm_lsp_dir . '${_erlang_ls_dir}/erlang_ls/_build/default/bin/erlang_ls' ), '--transport', 'stdio' ],
  \     'project_root_files': [ 'erlang_ls.config', 'erlang_ls.yaml' ]
  \   },
  \ ]
EOF
  5. Populate an Erlang file with functions that have a doc-text 
    tee /tmp/erlang_ls_vim_test.erl 1>/dev/null <<'EOF'
-module(erlang_ls_vim_test).

-export([do_it_doc_functions/1, do_it_doc_specs/0, uses_a_bif/0]).

-doc """
This line should show up but does not
""".
do_it_doc_functions(_Ignored) -> ok.

-doc """
This line should show up but does not
""".
-spec do_it_doc_specs() -> wat.
do_it_doc_specs() -> wat.

uses_a_bif() -> exit(woot).
EOF
  6. Place cursor on do_it_doc_functions and/or do_it_doc_specs, then in Vim Ex mode run :YcmCompleter GetHover to force client to request info from Erlang LS

Expected behavior

I expect -doc """Text""". to be discovered/displayed for custom functions, and other code, similar to how -doc """Text""". is discovered/displayed when hovering over built-in/standard-library code

Actual behavior

  • Place cursor on do_it_doc_functions and via Vim Ex mode execute :YcmCompleter GetHover, and one gets the following; 
    ## do_it_doc_functions/1
  • Place cursor on do_it_doc_specs and via Vim Ex mode execute :YcmCompleter GetHover, and one gets the following; 
    ## do_it_doc_specs/0

---

```erlang
-spec do_it_doc_specs() -> wat.
```

    Note; above is true regardless of if one has the cursor on the -spec's specified function, or function itself.

  • Place cursor on exit and via Vim Ex mode execute :YcmCompleter GetHover, and one gets the following; 
    ```erlang
exit(Reason) -> no_return() when
      Reason :: term().
```

---

```erlang
Raises an exception of class `exit` with exit reason `Reason`.

As evaluating this function causes an exception to be raised, it has no return value.

The intent of the exception class `exit` is that the current process should be
stopped (for example when a message telling a process to stop is received).

This function differ from [`error/1,2,3`](`error/1`) by causing an exception of
a different class and by having a reason that does not include the list of
functions from the call stack.

See the guide about [errors and error handling](`e:system:errors.md`) for
additional information.

Example:

```erlang
> exit(foobar).
** exception exit: foobar
> catch exit(foobar).
{'EXIT',foobar}
```

> #### Note {: .info }
>
> If a process calls [`exit(kill)`](`exit/1`) and does not catch the exception,
> it will terminate with exit reason `kill` and also emit exit signals with exit
> reason `kill` (not `killed`) to all linked processes. Such exit signals with
> exit reason `kill` can be trapped by the linked processes. Note that this
> means that signals with exit reason `kill` behave differently depending on how
> they are sent because the signal will be untrappable if a process sends such a
> signal to another process with [`erlang:exit/2`](`exit/2`).
```

    Note; above output though correct in capturing content seems incorrect in how it is wrapping everything with \`\`\`erlang for the whole documentation -doc """Text""", because that breaks any internally defined language block's formatting... But that may be better as a different Issue 🤷

Context

  • erlang_ls version (tag/sha): sha b8724fb8402c822da5e6d36d1711ac67fef76389
  • Editor used: Vim (classy flavored) via Arch (BTW™) version 9.1 with included patches: 1-1043
  • LSP client used: YouCompleteMe via ycm-core/lsp-examples PR#44 installation and configuration
  • Doing a bit of vimgrep-ing showed the following file locations may be where -doc parsing behaviors are defined 
    apps/els_lsp/src/els_code_actions.erl|654 col 30-34| <<"browse-docs">>,
apps/els_lsp/src/els_completion_provider.erl|862 col 12-16| <<"-doc \"\"\"Text\"\"\".">>,
apps/els_lsp/src/els_completion_provider.erl|872 col 12-16| <<"-doc false.">>,
apps/els_lsp/src/els_completion_provider.erl|882 col 12-16| <<"-doc #{}.">>,
apps/els_lsp/src/els_completion_provider.erl|892 col 12-16| <<"-doc File.">>,
apps/els_lsp/src/els_execute_command_provider.erl|31 col 18-22| <<"browse-docs">>
apps/els_lsp/src/els_execute_command_provider.erl|212 col 26-30| execute_command(<<"browse-docs">>, [
apps/els_lsp/src/els_execute_command_provider.erl|233 col 26-30| execute_command(<<"browse-docs">>, [
apps/els_lsp/src/els_general_provider.erl|117 col 14-18| "text-document-sync",
apps/els_lsp/src/els_general_provider.erl|293 col 39-43| provider_id(textDocumentSync) -> "text-document-sync";

    ... But I ain't yet clever enough to know if/where something be missing.

Client/Server Logs After opening file

2025-01-28 14:25:18,478 - DEBUG - GET b'http://127.0.0.1:40665/ready' (None)
{'content-type': 'application/json', 'x-ycm-hmac': b'MUXESDkInOqPI+bqbKDCGjDaFDvJ7fxe0zONyaGfhv4='}
2025-01-28 14:25:18,493 - ERROR - <urlopen error [Errno 111] Connection refused>
2025-01-28 14:25:18,594 - DEBUG - GET b'http://127.0.0.1:40665/ready' (None)
{'content-type': 'application/json', 'x-ycm-hmac': b'MUXESDkInOqPI+bqbKDCGjDaFDvJ7fxe0zONyaGfhv4='}
2025-01-28 14:25:18,600 - DEBUG - GET b'http://127.0.0.1:40665/signature_help_available?subserver=erlang' ({'subserver': 'erlang'})
{'content-type': 'application/json', 'x-ycm-hmac': b'w4FYdhrtf0UOpBOg07ZBNftKESApT2jyJRX6qTSTY/A='}
2025-01-28 14:25:18,667 - DEBUG - POST b'http://127.0.0.1:40665/event_notification'
{'content-type': 'application/json', 'x-ycm-hmac': b'j1bM0E9f/0bY0IErlDzDY+S5p8no3ck0hlS7b2+aDVY='}
b'{"filepath": "/tmp/erlang_ls_vim_test.erl", "line_num": 1, "column_num": 1, "working_dir": "/tmp", "file_data": {"/tmp/erlang_ls_vim_test.erl": {"contents": "-module(erlang_ls_vim_test).\\n\\n-export([do_it_doc_functions/1, do_it_doc_specs/0, uses_a_bif/0]).\\n\\n-doc \\"\\"\\"\\nThis line should show up but does not\\n\\"\\"\\".\\ndo_it_doc_functions(_Ignored) -> ok.\\n\\n-doc \\"\\"\\"\\nThis line should show up but does not\\n\\"\\"\\".\\n-spec do_it_doc_specs() -> wat.\\ndo_it_doc_specs() -> wat.\\n\\nuses_a_bif() -> exit(woot).\\n", "filetypes": ["erlang"]}}, "ultisnips_snippets": [{"trigger": "def", "description": ""}, {"trigger": "modall", "description": ""}, {"trigger": "asn", "description": ""}, {"trigger": "%p", "description": ""}, {"trigger": "%s", "description": ""}, {"trigger": "fun", "description": ""}, {"trigger": "LGPL2", "description": ""}, {"trigger": "LGPL3", "description": ""}, {"trigger": "GMGPL", "description": "linking exception"}, {"trigger": "incl", "description": ""}, {"trigger": "foldp", "description": "Insert a vim fold marker pair"}, {"trigger": "diso", "description": "ISO format datetime"}, {"trigger": "rcv", "description": "Receive Expression"}, {"trigger": "asexc", "description": ""}, {"trigger": "MPL2", "description": ""}, {"trigger": "c)", "description": ""}, {"trigger": "modeline", "description": "Vim modeline"}, {"trigger": "aseq", "description": ""}, {"trigger": "aserr", "description": ""}, {"trigger": "asex", "description": ""}, {"trigger": "testsuite", "description": ""}, {"trigger": "beh", "description": ""}, {"trigger": "box", "description": "A nice box with the current comment symbol"}, {"trigger": "supervisor", "description": ""}, {"trigger": "asneq", "description": ""}, {"trigger": "gen_fsm", "description": ""}, {"trigger": "d", "description": ""}, {"trigger": "exp", "description": ""}, {"trigger": "MIT", "description": ""}, {"trigger": "||", "description": "List Comprehension"}, {"trigger": "itest", "description": ""}, {"trigger": "bbox", "description": "A nice box over the full width"}, {"trigger": "dt", "description": ""}, {"trigger": "BEERWARE", "description": ""}, {"trigger": "test", "description": ""}, {"trigger": "gen_event", "description": ""}, {"trigger": "foldc", "description": "Insert a vim fold close marker"}, {"trigger": "GPL2", "description": ""}, {"trigger": "GPL3", "description": ""}, {"trigger": "time", "description": "hh:mm"}, {"trigger": "ieunit", "description": ""}, {"trigger": "mod", "description": "Module Directive"}, {"trigger": "gen", "description": "Generator Expression"}, {"trigger": "WTFPL", "description": ""}, {"trigger": "undef", "description": ""}, {"trigger": "ifd", "description": ""}, {"trigger": "fold", "description": "Insert a vim fold marker"}, {"trigger": "lorem", "description": ""}, {"trigger": "pat", "description": "Case:Receive:Try Clause"}, {"trigger": "case", "description": ""}, {"trigger": "todo", "description": "TODO comment"}, {"trigger": "date", "description": "YYYY-MM-DD"}, {"trigger": "as", "description": ""}, {"trigger": "gen_server", "description": ""}, {"trigger": "AGPL3", "description": ""}, {"trigger": "uuid", "description": "Random UUID"}, {"trigger": "try", "description": ""}, {"trigger": "inc", "description": ""}, {"trigger": "asnmat", "description": ""}, {"trigger": "if", "description": ""}, {"trigger": "ddate", "description": "Month DD, YYYY"}, {"trigger": "BSD2", "description": ""}, {"trigger": "BSD3", "description": ""}, {"trigger": "BSD4", "description": ""}, {"trigger": "rec", "description": ""}, {"trigger": "ifnd", "description": ""}, {"trigger": "datetime", "description": "YYYY-MM-DD hh:mm"}, {"trigger": "ISC", "description": ""}, {"trigger": "AGPL", "description": ""}, {"trigger": "application", "description": ""}, {"trigger": "eunit", "description": ""}, {"trigger": "asmat", "description": ""}, {"trigger": "APACHE", "description": ""}, {"trigger": "%d", "description": ""}, {"trigger": "%e", "description": ""}], "event_name": "BufferVisit"}'
2025-01-28 14:25:18,669 - DEBUG - POST b'http://127.0.0.1:40665/event_notification'
{'content-type': 'application/json', 'x-ycm-hmac': b'nOdaeS+CFVFiY71PQAuh/mwwmd5CAARlT823g262550='}
b'{"filepath": "/tmp/erlang_ls_vim_test.erl", "line_num": 1, "column_num": 1, "working_dir": "/tmp", "file_data": {"/tmp/erlang_ls_vim_test.erl": {"contents": "-module(erlang_ls_vim_test).\\n\\n-export([do_it_doc_functions/1, do_it_doc_specs/0, uses_a_bif/0]).\\n\\n-doc \\"\\"\\"\\nThis line should show up but does not\\n\\"\\"\\".\\ndo_it_doc_functions(_Ignored) -> ok.\\n\\n-doc \\"\\"\\"\\nThis line should show up but does not\\n\\"\\"\\".\\n-spec do_it_doc_specs() -> wat.\\ndo_it_doc_specs() -> wat.\\n\\nuses_a_bif() -> exit(woot).\\n", "filetypes": ["erlang"]}}, "tag_files": [], "syntax_keywords": ["link", "monitor", "error", "port_command", "and", "self", "group_leader", "make_ref", "try", "put", "spawn_monitor", "tl", "port_close", "is_pid", "bxor", "max", "is_record", "end", "orelse", "size", "get", "unlink", "bsl", "pre_loaded", "now", "setelement", "date", "port_connect", "case", "length", "tuple_size", "xor", "unregister", "throw", "tuple_to_list", "atom_to_list", "is_bitstring", "iolist_size", "map_size", "rem", "list_to_bitstring", "bsr", "spawn", "register", "of", "bnot", "is_float", "demonitor", "erase", "binary_to_atom", "monitor_node", "disconnect_node", "list_to_float", "is_boolean", "binary_to_existing_atom", "binary_to_list", "float_to_binary", "list_to_pid", "trunc", "registered", "if", "begin", "is_list", "bor", "min", "else", "float", "not", "andalso", "node", "is_process_alive", "process_flag", "div", "fun", "check_old_code", "whereis", "list_to_atom", "band", "exit", "is_tuple", "byte_size", "pid_to_list", "list_to_tuple", "or", "apply", "abs", "hd", "check_process_code", "is_number", "process_info", "false", "split_binary", "term_to_binary", "binary_to_float", "iolist_to_binary", "list_to_integer", "round", "when", "statistics", "is_atom", "time", "halt", "nodes", "binary_to_term", "load_module", "open_port", "list_to_existing_atom", "binary_to_integer", "is_map", "is_reference", "purge_module", "module_loaded", "concat_binary", "is_port", "spawn_opt", "maybe", "is_alive", "bitstring_to_list", "spawn_link", "process", "cond", "alive", "is_integer", "atom_to_binary", "garbage_collect", "receive", "integer_to_binary", "element", "let", "integer_to_list", "after", "is_function", "is_binary", "list_to_binary", "float_to_list", "get_keys", "binary_part", "bit_size", "catch", "is_map_key", "true", "delete_module"], "event_name": "FileReadyToParse"}'

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions