Possibility to improve Protocol-implementation documentation in ExDoc?

[Wiebe-Marten Wijnja]

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

[José Valim]

The trouble with this is that protocol implementations are dynamic. So for example, a protocol provided by Ecto will have two or three implementations, but for someone using Ecto inside Phoenix, the protocol will have many more implementations that won't be reflected in the Ecto documentation.

The only entity that has a full view of all protocol implementations is your application. Which is why it is the only place we can perform consolidation.

I am not sure we have a better answer besides making this more accessible at runtime (which I think "i String.Chars" in IEx already supports).

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--
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 elixir-lang-core+unsubscribe@googlegroups.com.
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.

[Wiebe-Marten Wijnja]

Thank you for your reply, José.

> So for example, a protocol provided by Ecto will have two or three implementations, but for someone using Ecto inside Phoenix, the protocol will have many more implementations that won't be reflected in the Ecto documentation.

Yes, but what I propose above is the inverse: Listing the protocols that are implemented for a datatype on the datatype's documentation page, rather than listing the implementations for a protocol on the protocol's documentation page.

This proposal follows this logical reasoning: 

To implement a protocol, both the datatype and the protocol need to be in scope.

A protocol is only useful if there exists at least one (but preferably many) implementations of it.

On the other hand, a dataype is already useful even if it does not implement any protocols.

Therefore, it follows that:

There are many libraries containing a new datatype that implements a prior-existing protocol.

And there are fewer libraries containing a protocol and implementing it for a prior-existing datatype.

(This can also be considered the Dependency Inversion Principle in practice)

The exception to this rule are protocols for which Elixir's built-in datatypes receive implementations.

However, whilst it is rare, it does happen that the original protocol, the original datatype and the implementation of the protocol for that datatype live in separate libraries. 

An example would be {Ecto (datatype), PhoenixHTML (protocol), PhoenixEcto (implementation)}. This example is similar to, but different from, the example José gave. 

(Side note: PhoenixEcto does not host any documentation at all right now, because it only contains protocol implementations(?))

My proposal as stated above works for the majority of cases (in which above reasoning works), but it does not work for all of them, so maybe we need something better. 

Maybe we could add a 'Protocol Implementations' tab to the menu in ExDoc (Below 'Pages', 'Modules', 'Exceptions', 'Protocols'), and list the implementations that are written out in the current library there. 

Their pages would be presented just like normal module pages, with the addition of a reference to both the implemented protocol and the implementing data type's module page at the top.

This would work for nearly all cases.

Only the cases in which code conditionally implements protocols based on today's horoscope will ExDoc be unable to extract the implementation documentation properly. But in that case I'm sure the developer has more dire problems to solve ;-p .

On top of adding a 'Protocol Implementations'-tab to ExDoc, we could also refer to that page from the Protocol or data type if they happen to be in the same library. (With a disclaimer stating that only implementations made in this library are shown here)

~Wiebe-Marten/Qqwy

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

[José Valim]

> Yes, but what I propose above is the inverse: Listing the protocols that are implemented for a datatype on the datatype's documentation page, rather than listing the implementations for a protocol on the protocol's documentation page.

It has the same issue, we don't know all protocols that a data-structure implements when generating the docs. Only part of them.

> However, whilst it is rare, it does happen that the original protocol, the original datatype and the implementation of the protocol for that datatype live in separate libraries. 

It is the opposite of rare. Let's take Phoenix as an example:

1. All data-types in the Elixir standard library will be unable to show specific Poison/Ecto/Phoenix protocols implementation - unless we list the data type again in the documentation of those projects, which would be confusing.

2. Decimal is a separate library and we wouldn't be able to show it can, for example, be converted to JSON

3. Phoenix.HTML defines protocols but no new data-types, so what implements those protocols will be lost too

The only data type that will possibly be correct is Phoenix.Socket and that information will be outdated as soon as you depend on another library that implements a protocol for Phoenix.Socket.

Trying to statically generate documentation for protocols/implementations will face all problems protocols are meant to solve.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D