[FEATURE] - Include signature comments below function separator

[ypnos]

Often, comments directly above a method are used to describe its signature (e.g. Doxygen).

It would be great if any comment lines above a function could be included below the separator. Example (LUA):

[alefragnani]

Hi @ypnos ,

The same request has already been made, in #8, and ended up being closed by the user.

This was my comment (link: https://github.com/alefragnani/vscode-separators/issues/8#issuecomment-727079417):

The extension uses the VS Code/extensions engine to detect the Symbols (Methods, Functions and Constructors). Doing so, location it uses to draw the lines, depends entirely on these engines. I don’t do any kind of parsing on the source code. And Comments, is not a SymbolKind supported by VS Code.

To support this feature, parsing is mandatory. I know a few programming languages, and I remember different syntax for comments on each of them. So, in fact, it would require a few parsers.

I didn't say it's not possible. It's just a matter of a proper parser, for each language/comment syntax.

Let's leave it open, so others can contribute/upvote.

Hope this helps

[ypnos]

I'm sorry I went too quickly over closed issues to spot #8.

I looked through your code and it seems like you obtain a list of symbol references and then just add a decoration directly on those. I wonder, is it possible from the symbol to obtain its context in the file? Like, would it be possible to obtain the text line above the symbol and parse it, and optionally add the decoration to that line?

Please correct me if I'm wrong, but it looks like you obtain DocumentSymbol instances which give you a range within the document, from the starting point of which you could look behind in the document.

In this case I would expect this to be more feasible. Detecting signature comments in most programming languages would boil down to a simple regex on the line. E.g. ^\s*(\/[\/\*]|\*|--|#|%). This one covers the most prevalent languages, yet there is quite a few more symbols used by more niche languages (good overview).

A single regex would most probably suffice for all languages though, simply because we require lines to start with these symbols, and, e.g., in C++ no line starts with '#' or '--' just above a function declaration/definition, and while, e.g. in Python '//' is an operator, it wouldn't appear above a def line just like that. And block comments used for signature descriptions are typically using a block format (e.g. C++, /* .. * .. * .. */ instead of /* .. .. .. */, where we would lose the middle lines without real parsing). The regex could further be configurable by the user.

How do you see such an approach?

[alefragnani]

That's exactly what I was saying 😬.

I wouldn't replace the DocumentSymbol API in favor or a Parser, mostly because the DocumentSymbol API works out of the box for every language the user has installed.

The solution should combine both, similar to the way you commented. Using the DocumentSymbol, the extension detects every symbol the document has. Then, if a symbol can have comments above, use the parser/regex to check, and if found, update the range to start from there.

It should be a opt-in behavior, and I wonder if every comment above a symbol should be recognized, or only those above Classes and Functions.

[ypnos]

Sounds great! Your mention of language parsing gave me the impression some real parsing needs to be done. But I believe for a first quick solution, opt-in, a tunable regex that greedily includes lines would be effective enough.

[alefragnani]

No, no need for a real parsing. The DocumentSymbols API works pretty well and we should take advantage of it.

Unless, of course, you are using some language which doesn't provide DocumentSymbols today (just provides syntax highlighting). But, in this case, the Separators extension already doesn't work.

[DarkTrick]

I'm in a similar situation with my own extension. I'm planning on simply parse by "no empty line". Every line above the function head, that is not empty extends the function head.

Example:

                                <-- draw line here
/** this is a comment **/
function foo(){}

/** this is a comment **/
                          <-- draw line here (there was an empty line between func an comment)
function foo(){}

                           <-- draw line here (probably even two lines)
function foo2(){}
function foo(){}

↑ sure, this is not optimal, but I wouldn't care about this edge case.

[alefragnani]

Hi @DarkTrick ,

Have you managed to deliver your extension with the "no empty line" solution? That was exactly one of the possible rules on this matter, merged with a regex to detect for comments.

I hope to start looking at this next week, after releasing the August update.

[DarkTrick]

@alefragnani I had a instable test system running (VSCode works kind of very unexpected in this area), but unfortunately I had to put it on hold for burning stuff ever since that comment. It's still on my list, but there are a couple of things that need to be done, first.

[shayded-exe]

I think the "no empty line" method would be great to have. I sometimes will put a variable used by a function on the line right above to group them. Maybe have a max # of lines it will expand in case two blocks are touching.

[alefragnani]

Hi everyone,

This feature is planned to be available in the next release. The question is, how do think the new feature would be enabled?

I mean, this won't be enabled by default, but as an opt-in, and I would like to know your opinion about it.

Please vote in the Poll https://github.com/alefragnani/vscode-separators/discussions/93. It will be up for a week, in order to collect your feedback.

Thank you

[alefragnani]

The poll has ended, and the winner option is Update the separators.location setting,...

Thanks for your votes.