Documentation for core.common

[takase1121]

Closes #1505.

[jgmdev]

So far looking beautiful

[Guldoman]

I wonder if we should always use # before descriptions.
We need to put up an annotations style guide.

[Guldoman]

We really need guidelines for this.
For example it might be better to avoid adding the initial ---, as well as avoiding the space between params and returns. Or even standardize the use of # for descriptions.

[takase1121]

We really need guidelines for this. For example it might be better to avoid adding the initial ---, as well as avoiding the space between params and returns. Or even standardize the use of # for descriptions.

the leading dashes are from docs/. I'm following an existing style as guidelines.

[Guldoman]

Yeah, I get that, but it might be a bit too verbose for in-source annotations.

[takase1121]

I've updated the docs to fix some errors and rephrase some confusing parts.
I don't really have any solid guidelines, aside from a few points I followed when writing docs.

1. The description is split into a brief and detailed descriptions. Each description generally has one or two sentences that explains what the function does. Sometimes some function can have extra stuffs, so I placed a linebreak and continue with more detailed explanations.
2. All parameters have types. Avoid the use of any as much as possible. Descriptions are good when the parameter name is not self explanatory (e.g. the files parameter for fuzzy search, what does it do exactly?)
3. If the function accepts multiple types of parameters and return different types of values based on the input, use @overload to properly document them. @overload does not allow you to add type-specific descriptions, so make sure that it is covered in @param or description.
4. return types should always be documented. Return variable name is optional, but if you think it helps with readability then add it. Return descriptions are generally avoided (because they don't really look good in my opinion), but is used when the function returns something you wouldn't expect.
5. Keep descriptions in @param, @field, @return short. For some reason LuaLs devs thinks that putting a newline in these descriptions will produce a linebreak, and for @field you'll have to put the multiline description before the @field annotation. It makes the doc look stupid unless you have LSP.

[takase1121]

I opted to make some parameters type|nil instead of making it optional, because they aren't supposed to be optional. For instance, common.merge allows both arguments to be nil, but it does not make sense to call them optional as it implies common.merge(). Instead, a should be table|nil which implies common.merge(nil) which is a more likely scenario.

[Guldoman]

I opted to make some parameters type|nil instead of making it optional, because they aren't supposed to be optional.

Yeah I'm alright with that.