Idea: show type signature at the top of all terms with docs #222
Description
I’ve got a few ideas for how to improve the API doc viewing experience. First, take a look at https://share.unison-lang.org/@blj1mhqin19isesr8sn1648nhi061kt8urt8eg6nui2arvq1ga1pe617ukq9r4l7trlau21h3eldq5m7n8rvud88686u0qa71jerk40/terms/base/Random/natIn
When you’re reading API docs in a typed language, you almost always want to know the type signature, as that gives you context to understand the prose which fills in more details. Right now, you have to jump down to where the source code is to see the signature. I find myself jumping down there and then back to read the rest of the docs, which is not a good experience.
Note that while users can manually include type signatures in their docs, I think it’s better to standardize on the API doc viewing experience rather than relying on everyone following the same convention.
Originally we elided the signature from the top of the definition because it was redundant with the signature included with the source code. With docs, there’s often quite a bit of spacing between the docs and the signature so I think it makes sense to include it at the top.
One idea that might be worth exploring - include the source code at the top, but folded so only the signature is shown. Immediately below that is the docs. 95% of the time, when browsing API docs I don’t need to see the source code (if the docs are good, anyway).
Regardless of where the signature is or if it’s included in two places, I suspect Share should start out with the source code folded.