Closed nomeata closed 9 months ago
Originally we used to have the ctor documentation above the ctor type but that was changed by @eric-wieser. If we do this change of swapping the whole type docs above the thing, would it be sensible to also reswap the ctor doc? And what do you, Eric, think about switching the type doc above given that you originally advocated for the ctor doc switch?
I still firmly believe that constructors and fields names should be shown before their descriptions. I don't think I ever expressed an opinion on where the main docstring belongs, beside it appearing somewhere after the name.
So inductive name, type, docs, followed by list of ctor, type, docs makes sense, does it?
Consider a user trying to find out what
Std.Format
is. They navigate tohttps://leanprover-community.github.io/mathlib4_docs/Init/Data/Format/Basic.html#Std.Format
and the first thing they read is that
.nil
is “The empty format”. Only a good page further down, and separated from the last constructor’s doc with only an easy-to-miss change of indentation and font size, they findWould it be possible to put the main documentation for the structure/inductive before the fields? See maybe the Haskell docs for inspiration.