Developer notes

Assumptions about comment leaders

Nothing is guaranteed if a setting violates any one of these assumptions.

• simple leaders and opening leaders do not start with whitespace
  • when line-initial they start exactly at ^\s*\zs\S
• closing leaders do not end in whitespace
• all leaders consist of at least one \S character

The 'cms' setting for Cobol violates the first assumption, the Visual Basic 'com' setting violates the second one.

'comments' flags

Treatments of 'comments' flags.

b (needs space)    ignored, simple leader search
n (nested)         ignored, simple leader search
O (open above)     ignored, simple leader search
empty              simple leader search

f (list-like)      unused

s (start)          paired leader search
m (middle)         unused
e (end)            paired leader search
l (left-align)     ignored, paired leader search
r (right-align)    ignored, paired leader search
x                  ignored, paired leader search
digits             ignored, paired leader search

Overlapping paired leaders

Overlapping full-line paired leaders like the following aren't handled properly at the moment.

<!--->
/*/

The problem is that we can't really decide which part of the leader string to take seriously -- is it an opening leader with a bogus closing leader, or is it a closing leader with a bogus opening leader?

In inline comments, these are recognized and interpreted, but not necessarily the way the parser is going to interpret them.

Multi-byte characters

Everything should work with multi-byte characters in the source code, but comment characters must not contain multi-byte characters.

Limitations

Things we cannot handle:

• embedded language comments
  • this concerns Perl POD as well
• language-specific commenting conventions such as Python docstrings
• nesting of paired comment leaders
  • e.g. OCaml allows nesting of comments (* outside (* inside *) outside *). In C or XML this would be invalid, or rather only /* outside /* inside */ would be part of the comment.
• list-like "comments" (not really comments), the ones that carry the f flag

Things we do not handle:

• Hanging end-of-line comments:

  let g:q_var = has_blob ? blob : []  " assign blob to the
                                      " omnipotent q_var
  

• Multi-line inline comments:

  Iterator<FruitBasket> iter = /* why does this comment
          span two lines? */ fruitBasketContainer.iterator();