How to document @field values (description not shown when hovering the function)

---@class Foo
---
---desc1
---@field dostuff fun(param1: integer) # desc2
foo = {}


function foo.dostuff(param1)
	print(param1)
end

I have an api defined in my meta file with functions the user can define. According to the documentation https://luals.github.io/wiki/annotations/#field

The syntax is this one: ---@field [scope] <name[?]> <type> [description]
A bit sad that the description has to come after the field and can not be above it. If the type is already a long callback the entire annotation line with long description will be super long :(

Anyways even that one I could not get to work. My editor would not show the description when hovering the function. Also I could not go to its definition to at least manually browse the type annotations.

Interestingly enough, if the table is made local, it works as expected:

Once it is made global, the description disappears:

As for defining functions in a @field, there are various known limitations that could hopefully be fixed with a @function annotation.

Oh nice catch with it working as local. Sadly I can not use this workaround :/ because the type annotation comes from a meta file and is defined in C++ so without the global definition the instance of the table would not be in scope at all as far as I understand.

Dropping by again to say that I found a workaround. Define the class first and then set the instance's @type:

Code

---@class Actor
---A table that maps a MIME type to a serialization function.
---
---Each serialization function must accept `Actor` as a parameter and return
---a string representation of it.
---@field serializers table<string, fun(v: Actor): string>
---Execute the given action. A success boolean and error message will be returned
---
---See some documentation about it
---@field execute fun(action: string): boolean, string

---@type Actor
myActor = {}

Also, it looks like this issue of fields not being accessible on globals has already been reported, so I'm going to mark this as a duplicate.

Thanks for another workaround c:

Sadly it did not work at all for me and made everything worse xd. Maybe because its in a meta file. Anyways I will survive.

Navigation Menu

Repository navigation

How to document @field values (description not shown when hovering the function) #3373

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

How to document @field values (description not shown when hovering the function) #3373

Description

Activity

carsakiller commented on Mar 10, 2026

ChillerDragon commented on Mar 11, 2026

carsakiller commented on Mar 18, 2026

carsakiller commented on Mar 18, 2026

ChillerDragon commented on Mar 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions