Update documentation for unitid handling

[Tomotz]

Add note about unitid validity and return behavior.

[lep]

Couple of style questions:

1. Should we just write that in the freeform text for the function instead of a note?
2. Should we use nil or null or nil/null?

[Luashine]

1. It should be in "freeform", because it pertains to the return value. In other words, at the very top as it's the main functionality.
2. I would prefer to stick to null for two reasons: a) Jass is the main doc language despite an increase in Lua usage. b) null is much easier understood by newcomers than a pretty niche "nil" used by Lua.

Three: it's already part of my off-branch work here: https://github.com/Luashine/jassdoc/blob/f3a666c00f64aadb49b0bd60ff9b722a6634698a/common.j#L18487-L18490

Technically, I would leave this PR open until I can start a merge of my stuff. I will have time to continue work on this after Wednesday. // Tomotz, I'm sorry if this delay has caused you issues with debugging etc.