Fill in undocumented descriptions

[DaanV2]

Some of the schemas still contain "description": "UNDOCUMENTED" and is probably best to be resolved into good explanations

[Xterionix]

A lot of places have "$comment": "UNDOCUMENTED" but have a description is it safe to remove this line? Or is it being kept for something?

[DaanV2]

It kept to indicate it was based around knowledge gathered and not from the documentation, as it might have not existed at that point

[Xterionix]

So it's not part of the scope of this issue

[DaanV2]

Yes, indeed :)

[BrodBlox09]

When filling in undocumented descriptions should they be formatted as full sentences ending with periods or sentence fragments without a terminating period? I've seen examples of both throughout the code base and there is no declarative style guide here to resolve this. My preference is to always use punctuation because when you have 2 or more sentences it feels weird to use periods in the middle and none at the end, though it does feel more clean to use no periods when there is only one sentence.
What's even more annoying is I can't follow the official documentation's style guide rules on this because they don't provide anything for this and I've seen examples with and without periods all across the docs over there too.
I don't feel like this requires a whole new issue but I would like for the style guides for contribution to be more clear for this reason, or at least a note saying punctuation usage can be determined by the contributor.

[DaanV2]

When filling in undocumented descriptions should they be formatted as full sentences ending with periods or sentence fragments without a terminating period? I've seen examples of both throughout the code base and there is no declarative style guide here to resolve this. My preference is to always use punctuation because when you have 2 or more sentences it feels weird to use periods in the middle and none at the end, though it does feel more clean to use no periods when there is only one sentence. What's even more annoying is I can't follow the official documentation's style guide rules on this because they don't provide anything for this and I've seen examples with and without periods all across the docs over there too. I don't feel like this requires a whole new issue but I would like for the style guides for contribution to be more clear for this reason, or at least a note saying punctuation usage can be determined by the contributor.

It's pretty free form, but mainly because I'd rather do anything style-related through automated tools than having to pay attention to it through review. Though adding linters to json schema's is not really easy 😓

Though I always accepted anything that improves documentation into better language / syntax / readabillity