Use Struct instead of __struct__/0 in sidebar

[eksperimental]

Closes #1433

/cc @NickNeck

There is one issue though, is that %Task{} is not a function

[NickNeck]

There is one issue though, is that %Task{} is not a function

That is true. Before I have report the issue I was not aware that we can add @doc to defstruct. I was just confused that the side bar said something different than the page. I think %Task{} should be ok because that is equivalent to __struct__0.

[josevalim]

That's a good point.

The other thing to consider is that we have other public structs in the standard library: at least URI and Version, but those do not document their __struct__ versions. Version has documentation in the middle of the module body.

Should they all document __struct__ and then we merge this? Or should we no longer document __struct__ for task and then not merge this? What is your take @eksperimental?

[eksperimental]

I think that if it is renamed '%Struct{} it should not be under Functions.
Since it is a special case, I think we could create a new section after "Summary" or "Types"called "Struct", which will have no arrow (same like Summary) and it can show the documentation for __struct__/0.
We may no longer document __struct__/0 for Elixir, but what about other projects already doing it.

I think it add value, and it encourages users to document __struct__/0 to add this feature to their docs.

[josevalim]

I think that if it is renamed '%Struct{} it should not be under Functions.

I don't think that's an issue. Macros are under functions too since at the end they are functions that receive and return AST.

Structs are also powered by functions. I think it is all fine. I guess another option is to rename it to API, but I think functions does the job. If we are going to move to its own section, then I would rather not do it. If other projects are documenting __struct__/0, then they can continue doing so, and I think showing that the docs are "ugly" would be a good indicator for them to stop doing it. :)

So with all that said: Should they all document __struct__ and then we merge this? Or should we no longer document __struct__ for task and then not merge this? Did I change your mind in any way? :)

[eksperimental]

Why does it have to be all or nothing?

A quick search throws these files are usin defstruct: (deprecated and hidden should be excluded from the list)

lib/elixir/lib/calendar/date.ex
lib/elixir/lib/calendar/date_range.ex
lib/elixir/lib/calendar/datetime.ex
lib/elixir/lib/calendar/naive_datetime.ex
lib/elixir/lib/calendar/time.ex
lib/elixir/lib/code.ex
lib/elixir/lib/code/formatter.ex
lib/elixir/lib/config/provider.ex
lib/elixir/lib/dynamic_supervisor.ex
lib/elixir/lib/file/stat.ex
lib/elixir/lib/file/stream.ex
lib/elixir/lib/gen_event/stream.ex
lib/elixir/lib/hash_dict.ex
lib/elixir/lib/hash_set.ex
lib/elixir/lib/inspect.ex
lib/elixir/lib/inspect/algebra.ex
lib/elixir/lib/io/stream.ex
lib/elixir/lib/kernel/utils.ex
lib/elixir/lib/map.ex
lib/elixir/lib/map_set.ex
lib/elixir/lib/module.ex
lib/elixir/lib/protocol.ex
lib/elixir/lib/range.ex
lib/elixir/lib/regex.ex
lib/elixir/lib/stream.ex
lib/elixir/lib/task.ex
lib/elixir/lib/uri.ex
lib/elixir/lib/version.ex
lib/ex_unit/lib/ex_unit.ex
lib/ex_unit/lib/ex_unit/diff.ex
lib/iex/lib/iex/history.ex
lib/iex/lib/iex/server.ex
lib/logger/lib/logger/backends/console.ex
lib/mix/lib/mix/dep.ex
lib/mix/lib/mix/release.ex
lib/mix/lib/mix/shell.ex
lib/mix/lib/mix/task.compiler.ex

[wojtekmach]

I believe it is not a question of how many defstructs we have in core but rather how many of them are documented. (never mind!) I think it is all or nothing because we want to be consistent and predictable. I think it is quite nice that we have special case for %Struct{} in docs. It is tangential, but I'd even extend it and show sigil_D as ~D. However, if we should be documenting all %Struct{}s then I am not sure how it plays with structs that aren't really supposed to be constructed manually like %Date{}. Would documenting %Date{} and friends be useful?

[eksperimental]

Would documenting %Date{} and friends be useful?

I would say so. It aids when pattern matching them

[josevalim]

So then we should merge this PR and make an effort to document all public structs in Elixir on top of defstruct.

Note that, because __struct__ starts with underscore, it is hidden by default.

[eksperimental]

So then we should merge this PR and make an effort to document all public structs in Elixir on top of defstruct.

Maybe we could post in ElixirForum asking people who want to contribute to it.
It is also a good way to to engage people in the language, and it seems like a low hanging fruit.

I have been wanted to do something like this with all the Exceptions. as of now the only way to know how most of them work is by reading the source code.

[wojtekmach]

Ship it!

[josevalim]

Exceptions are trickier because nothing in an exception is public unless explicitly said otherwise. And I don't think we should go ahead and make everything all of our exceptions public, except for a few, such as ArgumentError and RuntimeError.

[eksperimental]

Exceptions are trickier because nothing in an exception is public unless explicitly said otherwise. And I don't think we should go ahead and make everything all of our exceptions public, except for a few, such as ArgumentError and RuntimeError.

I was no aware that they were meant to be private.

Still, writing about them, when they raised and maybe examples will be helpful for developers.