Ex_doc: Remove or use normal font for the "Specs" heading

[josevalim]

Today it is just repetitive and it gives the impression the current section, including the notes about the function definition, are all part of a section named "Specs".

[josevalim]

@eksperimental should we remove it or should we use normal font?

[eksperimental]

If we remove it, we should do something like we do with the functions that has the icon </>, and I 'm not sure if it will be clear enough conveying that those are the specs.

If we leave it, we need to change the font, as that font in normal weight looks bad.

Do we have other examples of documentation where the specs are shown. i would like to see how other people are tackling this issue

[josevalim]

If we leave it, we need to change the font, as that font in normal weight looks bad.

We would use the same found used in the regular text. That's what Erlang docs do too.

[josevalim]

Do we have other examples of documentation where the specs are shown. i would like to see how other people are tackling this issue

http://erlang.org/doc/man/lists.html#all-2

[eksperimental]

Playing with it, i think it's better to get rid of the colored background,

"Specs" uses same font like the spec code.

(it's just a sketch, i'm horrible with design) :-p

[josevalim]

@eksperimental I think Specs should either use the same font as all other headings (how it works today) OR it should be the regular text font. I don't think we should introduce yet another font/demarcation/heading. Removing the background also looks neat to me but I will delegate the decision to @dignifiedquire :)

[eksperimental]

Regular font, looks wrong. Size looks too big, I think due to the fact that it is being sandwiched by 2 blocks of smaller fonts

this is regular font, size: 0.90em

HEADING FONT (bold)

HEADING FONT (normal weight)

I would go with the last one.

[josevalim]

Here are a couple options too.

1. Regular font with proper spacing:

1. Keeping Specs as a headers but adding a Description header after the specs:

I like the second one but it almost feels like I am making the problem worse. It doesn't feel the Specs are properly place and this accentuates that.

[bbugh]

The Elixir docs are _wonderful_, especially in comparison to most languages, and I've noticed myself regularly struggling to remember function signatures. Having the specs there is helpful, but I think it is harder to remember because the type info is out of context of the signature.

Many languages use the types as parameter names (concat example: Ruby, Erlang, Elm), but ex_doc uses the friendly name, which is nice, but I think some variation where they're either in context above the signature or integrated into signature would make it more memorable and clear.

I like the idea of having them integrated into the function signature like other languages do. Dialyzer seems to get pretty verbose sometimes though, so I'm not sure how it would work in practice. Here's a few examples (accidentally using Enumerable.t instead of Enum.t, sorry!)

_#_1 Without variable names (my personal favorite):

_#_2 With variable names on a short method:

_#_3 With variables names, with types less bold:

_#_4 Longer functions, only types

_#_5 Longer function with both names and types:

_#_6 Here's a (not beautiful) example of the spec being above the signature like it is in the code.

Finally, the future concat example for Elixir? 😸

(incidentally, this was what I came to post an issue about)

[josevalim]

I actually like 6. It also brings more attention to the function header altogether, which is a common complaint. I would put it _under_ the signature.

I don't fix we can mix function definition with the specs though. Sometimes specs have multiple clauses, other times they have their own variables too.

[josevalim]

And thank you for the feedback @bbugh!

[dignifiedquire]

It is interesting there is such a discussion around this, as this was one of the sections I had the hardest time to design. While I generally like the ideas from @bbugh and agree with the sentiment, I don't think it would be good to have the function headers vary in their height.

The hard part about this section is that it can regularly be just a single spec, in which case it would make so much sense to merge it as @bbugh suggested, but it also can a list of many as @josevalim pointed out.

Generally I would be in favour of dropping the title Specs, as it doesn't help much in the current state. In addition, without the title there might be some more room to improve on the background/highlighting to make clearer that this describes the above defined function. I will think on that a bit more.

[eksperimental]

I was going to propose something like number 6, but couldn't design it.
it should be the specs before the signature, and the bar in the left with a lighter colour, and maybe lighter background color aswell.

[josevalim]

To continue moving the discussion here, here is a proposal for 6 where:

1. The specs comes after the signature (but with opaque 0.6)
2. The inside of the function is indented (1.2em)
3. The space between the function contents and headers are increased (from 0 to 1.2em)

[josevalim]

I have also added a title to the typespecs section so a short explanation appears on mouse hover but we cannot see it on the screenshot.

[eksperimental]

@josevalim that's beautiful, and that's what I meant in my last message (I expressed it backwards specs before signature)... but that's exactly what I meant!
Could you please send a screenshot of how it looks with a multi-line spec?

If it looks ok with multi-line spec i will just go with this one, and it conveys the message and it has brings zero distraction to the table.

thank you!

[josevalim]

@eksperimental can you find a multi-line spec? :D

Also, note to @josevalim: also tidy up the types section once this is approved.

[josevalim]

Ok, I found a multi-line one:

[josevalim]

Here are two other approaches. One makes the border and the whole bottom of the heading more opaque:

This keeps specs in its own section without background:

Thoughts?

[dignifiedquire]

I really like the last one, but fear that with the single line ones (which as far as I can tell are much more common) it gets lost easily.

[josevalim]

@dignifiedquire yup, I am afraid the last one puts us back where we started.

[bbugh]

For what it's worth, I like either the first or the second one. I'm strongly in favor of the spec being in the same context as the function. I think your first example @josevalim is what I would pick personally. 😄 Here it is in dark mode:

Another rendition with the primary function signature in slightly bigger text and a different background color for differentiation

[eksperimental]

I like Jose's second example.
playing with gimp, and take @josevalim's second exmple as a base, I have added a bottom border, and reduced the top padding of the spec (only on B and C)

I think the signature's bottom border draws a line (literally) between the signature and the spec.
So far I like B the best

A: Bars of same color, opaque background for spec
B: Different colors in bars, + bottom border for signature. Top padding in spec reduced.

C: Bars of same color, + bottom border for signature. Top padding in spec reduced.

[josevalim]

I have pushed the first option to master so people have something more accessible to play with: http://elixir-lang.org/docs/master/logger/Logger.html

I will continue to take feedback and improving it. I have also unified how we handle types with the remaining of the functions/callbacks. Compare how types work now on master with stable.

[michalmuskala]

It seems there's a bug where if the function name is the same as a type name it will be highlighted and linked to the type http://elixir-lang.org/docs/master/logger/Logger.html#level/0

[josevalim]

@michalmuskala that bug exists before this patch it seems. Please open up a new issue?

[josevalim]

This was approved by @dignifiedquire, so I am closing it.