Improve `multilineComments` and/or its documentation

[ppo]

I don't understand what the parameter multilineComments is and how it works.
It would be great to have more information about that in the doc/README.

What is considered multiline? Comments like /* */ and """ … """ in Python?

Actually, I would like multiline to work like this… (with Note: and Examples: tags)
Keep the formatting for all following comment lines that starts with a multi-space indentation (obviously not taking into account the first space between the comment symbol and the text).
Keeping the continuity if there's a blank line between inner-indented comments.

# Regular comment style. Lorem ipsum dolor sit amet, consectetur
# adipiscing elit. Etiam sollicitudin elit quis risus auctor lacinia sit
# amet sed odio. Integer sollicitudin quam vulputate.
#
# Note: Nulla vel consequat sem. Cras egestas varius justo sed ultrices.
#   Proin pellentesque sapien ut sollicitudin luctus. Maecenas eu feugiat
#   magna, non rhoncus libero. Cras porta tortor nisi, nec consequat tortor
#   aliquet a. Aenean luctus, velit sit amet.
#
#     This would still be styled like a note, even if more indented.
#   And this too as still inner-indented.
# Back to regular comment style.
#
# Examples:
#   - First example
#     This should ideally not break the continuity.
#     Even not a blank line between items? :-/
#
#   - Second one
#   - Last item
# Back to regular comment style.

[edwinhuish]

multilineComments is the parameter from https://github.com/aaron-bond/better-comments , it only enable/disable hightlight the tags in multiline comments.

Example: JS: /* */ HTML: <!-- --> Python: """ """

[matutter]

Hi, I came to ask about this too. I just switched to better-comments-next when I encountered this in python. Is it supposed to work like this @edwinhuish ? I have multiline enabled but dangling words do not get highlighted.

[edwinhuish]

No, it won't. You should use soft break, not hard break.

[ppo]

@edwinhuish By soft break, you mean automatic line break by the editor when word wrap is activated?… which means it's actually not multiline… and obviously not what's needed as the code is usually formatted with a max line length that is less than the editor window.

So long story short, multilineComments refers to multiline comments syntax, not comments on multiple lines using single-line comments syntax.

And there's no chance better-comments-next could/would handle that (comments on multiple lines using single-line comments syntax)?… because in practice, I (we all?) never comment the code using multiline syntax (except for functions, methods…).

Would it be possible to detect that the next line is indented, or does it work line by line?

[edwinhuish]

@ppo In your case, the problem is how to know where should the decoration end?

For example:

/**
 * ! This is a long long long long long long long long break
 * line should be hightlighted as alert.
 * But this line shouldn't be hightlighted.
 * TODO: this line should be hightlighted as TODO, NOT alert.
 */

So, the better soluction is add all prefix in each line for decoration.

[ppo]

@edwinhuish "Better solution" or easiest (i.e. no code/work/thinking required)? 😉
What would be better for the user? What would be the best user experience? That's what MUST be done. Can we find a solution to do that? Most of the time, yes… but are we willing to do what's necessary? ("No, I don't really care about this project" is a perfectly valid and understandable answer)

To answer your question, check my initial message, I showed that.

# Regular comment style. Lorem ipsum dolor sit amet, consectetur
# adipiscing elit. Etiam sollicitudin elit quis risus auctor lacinia sit
# amet sed odio. Integer sollicitudin quam vulputate.
#
# Note: Nulla vel consequat sem. Cras egestas varius justo sed ultrices.
#   Proin pellentesque sapien ut sollicitudin luctus. Maecenas eu feugiat
#   magna, non rhoncus libero. Cras porta tortor nisi, nec consequat tortor
#   aliquet a. Aenean luctus, velit sit amet.
#
#     This would still be styled like a note, even if more indented.
#   And this too as still inner-indented.
# Back to regular comment style.
#
# Examples:
#   - First example
#     This should ideally not break the continuity.
#     Even not a blank line between items? :-/
#
#   - Second one
#   - Last item
# Back to regular comment style.

[matutter]

“What would be better for the user” is subjective, not all users want the same thing. I would not want this extension to work in the ways you’ve outlined.

[edwinhuish]

better-comments-next works for all languages, you should think an easy way for all languages, not only one language. ( It's not enough demand to separate parser for different languages. )

In your example, # is line comment, it should not be parser as multiline comments.

And for the block comments.

EXAMPLE 1 ( with tag prefix in each line )

"""
! First example
! This should ideally not break the continuity.
! Even not a blank line between items? :-/

! Second one

! Last item
"""

EXAMPLE 2 ( your opinion, multiline with same space prefix )

"""
! First example
  This should ideally not break the continuity.
  Even not a blank line between items? :-/

! Second one

! Last item
"""

I don't think there's any particularly important difference between this 2 examples.

• better-comments-next only highlight the comments. Tag each line or tag one & hightlight multiline are the same.
• Same as your example, you wrote the comments with same prefix # (line comment) each line, make it like "block comments", you should do the same with better-comments-next too.
• If your editor has max line length limit, it's better to write the hightlight comment shortly, with description next line.
• The example 2 will cause many predictable matching errors and performance loss.

[ppo]

Thanks for your answer.
Sorry for my previous remark, I've been surrounded by too much mediocrity and stupid thinking these last weeks 😤
I don't know how better-comments-next works internally. I leave that to you.

Just to be clear. Tags can be more than a single character. So currently my example would actually have to look like this… Not pretty, right 😉

# Regular comment style. Lorem ipsum dolor sit amet, consectetur
# adipiscing elit. Etiam sollicitudin elit quis risus auctor lacinia sit
# amet sed odio. Integer sollicitudin quam vulputate.
#
# Note: Nulla vel consequat sem. Cras egestas varius justo sed ultrices.
# Note: Proin pellentesque sapien ut sollicitudin luctus. Maecenas eu feugiat
# Note: magna, non rhoncus libero. Cras porta tortor nisi, nec consequat tortor
# Note: aliquet a. Aenean luctus, velit sit amet.
# Note:
# Note: This would still be styled like a note, even if more indented.
# Note: And this too as still inner-indented.
# Back to regular comment style.
#
# Examples:
# Examples:  - First example
# Examples:    This should ideally not break the continuity.
# Examples:    Even not a blank line between items? :-/
# Examples:
# Examples:  - Second one
# Examples:  - Last item
# Back to regular comment style.

---

FYI: I never use multi-line comments (except when required) because in Python, it doesn't feel right. And old habit as it causes problem when you've to comment a large portion of code; which doesn't happen often, and is not the best habit anyway.

[edwinhuish]

PR welcome