Commented lines in export extern completions are joined to previous documentation

[epbuennig]

Describe the bug

Leaving comments after an argument or flag declaration inside an export extern cause incorrect descriptions when using the completions.

Consider an extern declaration like so, using the completion results in an incorrect description for --opt (Screenshot 1)

export extern "comp-me" [
  --opt         # opt docs
  # --comment-out # commented-out docs
  --arg         # arg docs
]

Comments seem to be allowed, as this produces the expected result (Screenshot 3):

export extern "comp-me" [
  # --opt         # opt docs
  --comment-out # commented-out docs
  --arg         # arg docs
]

How to reproduce

1. define completions with at least one argument/flag
2. add a comment in a new line after an argument/flag
3. use completions
4. observe incorrect description

Expected behavior

Lines that do not start with any argument/ flag names but contain only a comment are not appended to the previous argument's description verbatim (Screenshot 2).

Screenshots

Screenshot 1:

Screenshot 2:

Screenshot 3:

Configuration

key	value
version	0.72.1
branch	makepkg
commit_hash	777f746
build_os	linux-x86_64
build_target	x86_64-unknown-linux-gnu
rust_version	rustc 1.65.0 (Arch Linux rust 1:1.65.0-1)
cargo_version	cargo 1.65.0
pkg_version	0.72.1
build_time	2022-12-05 22:50:04 +00:00
build_rust_channel	release
features	database, default, trash, which, zip
installed_plugins

Additional context

No response

[sholderbach]

That's a good point! The question could become how you do proper multiline comments for the command usage. But in the flag positions descriptions probably are typically terse so we could maybe change the parse a little bit.

In general there are some open questions about the comment syntax, that might be worth considering with changes to comment parsing #6741 #6957

[epbuennig]

If multiline descriptions were to be supported by the completer, i.e. properly rendered as multiline, then perhaps \ at the end of the line could be used to make it clear that the next line is part of the doc comment. Multiline doc comment tokens are also a possible solution.

While the completions usually have terse descriptions, the actual help message of a command may not. Extern declarations are also included in help commands, which may warrant multiline not-so-terse descriptions for options.

[zoechi]

I'd expect at least an empty line between comment and item to separate a comment from the items before and after.

Perhaps only consider a comment directly before an item.
Only if there is none, use comments on the same line.