Feature request: clearer visual for optional parameters

[saralain]

In Lua documentation I'm able to mark a parameter as optional by setting the type to be (type|nil) (like @param optionalNum (number|nil) -- Optional number, defaults to 0. Some parsers, including Luau and VSCode's language server for Lua, support a question mark to mark a parameter as optional. (like @param optionalNum number? -- Optional number, defaults to 0) I'd like to see moonwave support both of these in a clear way.

Moonwave currently renders the nil union option just as the user wrote it, which is reasonable. I'd find it more useful if it translated this to marking the parameter as optional in documentation, though.

My proposal:

• If a parameter or return value type is postfixed with ?, it should be translated to (existing type[s] | nil)
• If a parameter's type contains a union with nil, the parameter should be visually marked as optional. Nil should be removed from rendered type unions

Here's a quick mockup of what it might look like:

--- @within Zoo
--- @param name string -- The name of penguin
--- @param marbles number? -- How many marbles the penguin has. Defaults to 5.
function Zoo:createPenguin(name, marbles) 
    -- ...code here...
end

ps: Thanks for writing this! I'm really appreciating having a node-based documentation tool for lua, especially one I'll be able to theme.

Semi-related to #4

[evaera]

Optional function arguments are already covered in the "Writing Types" page:
https://eryn.io/moonwave/docs/Types#optional-function-arguments

[saralain]

Yes, I am currently writing them in the way described on that page as a union with nil.

My request is to change how they appear - I have updated the title to clarify.

For a seasoned lua veteran, it's obvious that a union with nil means a parameter can be excluded. For a newbie, the word optional is a lot clearer.

The ? postfix is a nice-to-have, and probably could have been a separate issue

[evaera]

I think I find the (optional) text afterwards a little bit harder to parse quickly than a question mark after the parameter name. It might be valuable to normalize the types to one style though instead of having param?: string, param: string? and param: string | nil as possible options.

[saralain]

Normalizing would definitely help me. If whatever indication is used has a separate css class that would solve all of my problems.

I'll note that I found the Types page a tiny bit confusing when I was first looking - I think param?: string, param: string? are both luau syntax, right? I'm not using luau, so that left me with the union. Testing though, it does seem like I can also put a ? on the name/type in the @param tag, which passes through to the ui wherever I put it.