suggestion: always have the description come first in JSDocs for unstable symbols

[iuioiua]

A symbol being unstable is secondary compared to a description of what that symbol does. I suggest we move the description to be first, and any unstable notices second.

CC @thisisjofrank @crowlKats

[dsherret]

I'm not sure about this. It being moved to the end increases the chance of it being cut off in auto-complete. Also, when someone is going to use something, they should see right away that it's unstable.

[crowlKats]

this is a bug with docs.deno.com postprocessing of typings, for which i have a local fix, which will land later this week

[iuioiua]

To be clear, I suggest moving the unstable notice to the 2nd paragraph, not the last paragraph of the symbol's documentation. I think it's more important to the user to know what the symbol does, over its instability status.

this is a bug with docs.deno.com postprocessing of typings, for which i have a local fix, which will land later this week

Sorry, what exactly is a bug? Perhaps, we can have @experimental tags be somehow represented even in symbol lists like the screenshot I share.

[dsherret]

To be clear, I suggest moving the unstable notice to the 2nd paragraph, not the last paragraph of the symbol's documentation. I think it's more important to the user to know what the symbol does, over its instability status.

I don't agree with that. I think being unstable is the most important thing for someone to know. People rarely even read docs and I think it should be the first thing people see in capital letters in order to catch their eye. This is especially important given we no longer require --unstable for type checking unstable APIs.

[iuioiua]

Let's agree to disagree then 😛

Either way, perhaps the suggestion in my previous comment might satisfy both preferences. Maybe it could be an "unstable" button or similar next to the symbol name.