People are sometimes putting comments in the syntax list:
Is this a good thing?
- Should the list (be allowed to) be a table with
sytax | explanation
instead?
Or does it just add noise?
- Shouldn't the explanation come from examples and remarks?
People are sometimes putting comments in the syntax list:
Is this a good thing?
sytax | explanation
instead?Or does it just add noise?
I've been rooting around that specific page on Docs, and I've been trying to consider if that would look better or worse without the comments. My gut tells me it'd look worse, so I would prefer to keep those specific comments in there.
That said, it does muddle the scope of that field a bit. If it's intended just to be a place to house syntax, that doesn't help all that much, since I don't know why those parameters are there or what purpose they serve. If it's intended to do a bit more explanation, then I agree that we should be able to add a simple (~200 characters) blurb of what the syntax of this specific thing is, and why it's this way.