Right now, if you implement a protocol for a certain data type, this is not
reflected anywhere in the documentation.
Only if the creator of a library goes into detail about the protocol
implementation existing in e.g. the general module documentation of the
struct will the end user find out about it.
(Other than directly reading the source code of the library, of course).
Furthermore, while it already is possible to document the implementation of
a protocol (to clarify: You can document the function definitions inside
`defimpl`, and also the `defimpl`-module as a whole using @moduledoc.),
this documentation does not show up in ExDoc at all.
My proposal would be to:
1. Add a new 'Protocol Implementations' section that is shown below the
'Functions' section.
2. This section contains for each protocol:
a. The name of the protocol, with a link to the protocol page if it is in
the same library (Is there a way we could reference protocols from other
libraries easily here?)
b. Followed by the protocol implementation module documentation
c. followed by the protocol function implementations (with documentation)
in similar fashion as the normal functions on the page.
I think this would be a great addition to ExDoc because:
1. It will make the existence of protocol implementations for certain data
types more clear.
2. It will allow users of a library to discover and understand protocols as
they are used by the library's datatypes, even if the protocol itself is
_not_ part of that library.
3. It will allow authors to document protocol implementations, clearly
stating made design decisions (things like 'for maps, Enumerable.reduce
runs over the {key, value} pairs in an arbitrary order`).
Sincerely,
~Wiebe-Marten/Qqwy
--
You received this message because you are subscribed to the Google Groups
"elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/elixir-lang-core/89b04317-01d2-4075-acc1-31861e098374%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
