feat(theming): separate highlight for function declarations

[matoous]

[proposal]

Add separate highlighting scope for function (and method) declarations that allows styling the declarations differently from their calls. I noticed that in some editors the function declaration are styled differently from function calls which wasn't possible with the current highlight scopes.

If this gets the green light I will take a look at more languages and if they could be adjusted as well (although the scope of languages I am familiar with is quite limited).

Open question: do we also want to be able to style function and method declarations differently? Maybe adding also function.declaration.method would work.

Showcase:

after

before

[archseer]

Sublime/TextMate use entity.name.function:

Function and method names should be scoped using the following, but only when they are being invoked. When defined, they should use entity.name.function.

• variable.function

https://www.sublimetext.com/docs/scope_naming.html#entity

WDYT @the-mikedavis should we introduce the entity group (needs to be documented in the book too)?

[archseer]

Actually, a better option would be @function for declarations, @variable.function for invocations. Would need a cleanup in themes though and it might break existing themes :/

[the-mikedavis]

Yeah I think I would also prefer to change the function invocation scope instead of the definition scope. Changing the definition scope is tricky because a function definition could also be a method so you would need some way to combine those scopes

[matoous]

@archseer should this maybe rather be variable.other.function given we currently have variable.other.member for fields of composite datatypes?

[matoous]

So I tried to experiment with the approach above but the issue I am hitting is: I want to distinguish function/method declarations and function/method calls. With the approach where new scope is added (e.g. variable.other.function, variable.other.method, or just variable.method) I can only distinguish method calls but regular function calls (or built-in function calls) are highlighted the same as declarations which brings me to following:

Keeping both function declaration and calls under stingle scope makes things very verbose if we want to add the ability to distinguish between those two, e.g. given:

- `function` - Function and method declarations.
  - `special` (preprocessor in C)
  - `builtin` - Built-in functions (e.q. `println!` in Rust)
  - `method` - Methods
  - `macro`

if I wanted to distinguish declaration from call I would have to add:

- `function` - Function and method declarations.
  - `call` - Function call
  - `special` (preprocessor in C)
    - `call`
  - `builtin` - Built-in functions (e.q. `println!` in Rust)     <--- this is implicitly a call
  - `method` - Methods
    - `call` - Method call
  - `macro`
    - `call` - Macro call

which is imho sub-optimal as it mixes declarations and calls breaking the inheritence benefits.

Thus I wonder if following proposal would make sense: we add 2 scopes under function: declaration and call (the terms themselves are subject to change, tis just a suggestion) to distinguish declarations and calls and both can branch further to distinguish the function/method types, e.g.:

- `function` - Functions and methods.
  - `call` - Function and method calls
    - `special` (preprocessor in C)
    - `builtin` - Built-in functions (e.q. `println!` in Rust)
    - `method` - Method call                                <-- could also be moved under `variable.other.function`
    - `macro`
  - `declaration` - Declaration
    - `method` - Methods
    - `macro`

Theoretically, this could also be extended to remove function.call.method and have this scope under variable.other.function or variable.method instead. This will still most likely require quite a lot of manual work to ensure that all themes keep working as intended (can do that if this gets the green light) but I believe it could serve us better long term. My only concern is that this might be overcomplicated as I am not sure how far we want to go with the complexity of the highlighting scopes that we offer.

[archseer]

variable.other.function = I'd rather use variable.function to match old Sublime scopes

nvim-treesitter uses @function and @function.call but I agree these are a bit too close

I think you have a point with function.declaration.method etc but I think it's ok to make the theme author have to style the two scopes by hand since this is a more advanced theming that a lot of themes won't deal with in the first place.

My proposal:

• function/function.{method, builtin} should be definitions/declarations
• function.invoke/.call (or just variable.function to match existing Sublime/TextMate/VSCode grammars) should be any function or method invocation. It doesn't make sense to distinguish these, and we often can't on the grammar level anyway without a locals.scm query too which should cover this case