diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 7d552c980..2164bfc5e 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -3529,8 +3529,9 @@ Definition tables
     --  ^ Called sometimes; the string returned is passed to on_activate when
     --    the entity is re-activated from static state
 
-        -- Also you can define arbitrary member variables here
-        myvariable = whatever,
+        -- Also you can define arbitrary member variables here (see item definition for
+        -- more info)
+        _custom_field = whatever,
     }
 
 ### ABM (ActiveBlockModifier) definition (`register_abm`)
@@ -3646,6 +3647,12 @@ Definition tables
             end
         ^ The user may be any ObjectRef or nil.
         ]]
+        _custom_field = whatever,
+        --[[
+        ^ Add your own custom fields. By convention, all custom field names
+          should start with `_` to avoid naming collisions with future engine
+          usage.
+        ]]
     }
 
 ### Tile definition