4 files changed, 61 insertions, 8 deletions
diff --git a/changelog.md b/changelog.md
index 3b2a029c..77fedf65 100644
--- a/changelog.md
+++ b/changelog.md
@@ -13,6 +13,7 @@
         -- value is string here
     end)
     ```
+* `NEW` optional field `---@field name? type`
 * `CHG` [#549](https://github.com/sumneko/lua-language-server/issues/549)
 * `CHG` diagnostics: always ignore the ignored files even if they are opened
 * `FIX` completion: `type() ==` may does not work
diff --git a/script/core/hover/table.lua b/script/core/hover/table.lua
index 00f11659..c3a8fe95 100644
--- a/script/core/hover/table.lua
+++ b/script/core/hover/table.lua
@@ -15,16 +15,24 @@ local function formatKey(key)
     return ('[%s]'):format(key)
 end
 
-local function buildAsHash(keys, inferMap, literalMap, reachMax)
+local function buildAsHash(keys, inferMap, literalMap, optMap, reachMax)
     local lines = {}
     lines[#lines+1] = '{'
     for _, key in ipairs(keys) do
         local inferView   = inferMap[key]
         local literalView = literalMap[key]
         if literalView then
-            lines[#lines+1] = ('    %s: %s = %s,'):format(formatKey(key), inferView, literalView)
+            lines[#lines+1] = ('    %s%s: %s = %s,'):format(
+                formatKey(key),
+                optMap[key] and '?' or '',
+                inferView,
+                literalView)
         else
-            lines[#lines+1] = ('    %s: %s,'):format(formatKey(key), inferView)
+            lines[#lines+1] = ('    %s%s: %s,'):format(
+                formatKey(key),
+                optMap[key] and '?' or '',
+                inferView
+            )
         end
     end
     if reachMax > 0 then
@@ -34,7 +42,7 @@ local function buildAsHash(keys, inferMap, literalMap, reachMax)
     return table.concat(lines, '\n')
 end
 
-local function buildAsConst(keys, inferMap, literalMap, reachMax)
+local function buildAsConst(keys, inferMap, literalMap, optMap, reachMax)
     table.sort(keys, function (a, b)
         return tonumber(literalMap[a]) < tonumber(literalMap[b])
     end)
@@ -44,9 +52,18 @@ local function buildAsConst(keys, inferMap, literalMap, reachMax)
         local inferView   = inferMap[key]
         local literalView = literalMap[key]
         if literalView then
-            lines[#lines+1] = ('    %s: %s = %s,'):format(formatKey(key), inferView, literalView)
+            lines[#lines+1] = ('    %s%s: %s = %s,'):format(
+                formatKey(key),
+                optMap[key] and '?' or '',
+                inferView,
+                literalView
+            )
         else
-            lines[#lines+1] = ('    %s: %s,'):format(formatKey(key), inferView)
+            lines[#lines+1] = ('    %s%s: %s,'):format(
+                formatKey(key),
+                optMap[key] and '?' or '',
+                inferView
+            )
         end
     end
     if reachMax > 0 then
@@ -90,6 +107,19 @@ local function getKeyMap(fields)
     return keys
 end
 
+local function getOptionalMap(fields)
+    local optionals = {}
+    for _, field in ipairs(fields) do
+        if field.type == 'doc.field.name' then
+            if field.parent.optional then
+                local key = vm.getKeyName(field)
+                optionals[key] = true
+            end
+        end
+    end
+    return optionals
+end
+
 return function (source)
     local maxFields = config.get 'Lua.hover.previewFields'
     if maxFields <= 0 then
@@ -98,6 +128,7 @@ return function (source)
 
     local fields = vm.getRefs(source, '*')
     local keys   = getKeyMap(fields)
+    local optMap = getOptionalMap(fields)
 
     if #keys == 0 then
         return '{}'
@@ -127,9 +158,9 @@ return function (source)
     local result
 
     if isConsts then
-        result = buildAsConst(keys, inferMap, literalMap, reachMax)
+        result = buildAsConst(keys, inferMap, literalMap, optMap, reachMax)
     else
-        result = buildAsHash(keys, inferMap, literalMap, reachMax)
+        result = buildAsHash(keys, inferMap, literalMap, optMap, reachMax)
     end
 
     --if timeUp then
diff --git a/script/parser/luadoc.lua b/script/parser/luadoc.lua
index 3bb1b06e..83f59366 100644
--- a/script/parser/luadoc.lua
+++ b/script/parser/luadoc.lua
@@ -714,6 +714,10 @@ local function parseField()
     if not result.start then
         result.start = result.field.start
     end
+    if checkToken('symbol', '?', 1) then
+        nextToken()
+        result.optional = true
+    end
     result.extends = parseType(result)
     if not result.extends then
         pushError {
diff --git a/test/hover/init.lua b/test/hover/init.lua
index ff33944b..d9492fd1 100644
--- a/test/hover/init.lua
+++ b/test/hover/init.lua
@@ -1584,3 +1584,20 @@ local f
 [[
 local f: any
 ]]
+
+TEST [[
+---@class Position
+---@field x  number
+---@field y  number
+---@field z? number
+local <?t?>
+
+t.z = any
+]]
+[[
+local t: Position {
+    x: number,
+    y: number,
+    z?: number,
+}
+]]