search

erlef / documentation-wg

EEF Documentation Working Group
9 stars 1 forks source link

Implement -compile(warn_missing_edoc) #6

Closed moiseev closed 4 years ago

moiseev commented 4 years ago

Now that the doc comments become really first class citizens in the BEAM ecosystem. It would be nice if the compiler could warn about missing edocs on exported functions, not unlike -compile(warn_missing_spec). It is certainly possible to achieve the same result with a separate tool, but since warn_missing_spec is implemented in the compiler, it makes sense to follow suite if only for consistency.

I realize that this is very Erlang-centric description, but I am not familiar with other ecosystem languages enough to suggest a more generic problem statement.

josevalim commented 4 years ago

Hi @moiseev, I am not sure if this is the best place to have this discussion, as you said this is very centric to Erlang (and one of the tools in Erlang) and not about docs as a whole.

My humble opinion as an external person: I don't think it is the job of the Erlang compiler either, as Erlang's compiler doesn't know about edoc. Perhaps it should be a feature of edoc itself, which needs to be discussed with edoc maintainers.

moiseev commented 4 years ago

The same arguments apply to warn_missing_spec, don't they? Erlang compiler does not really care much about the specs (yes, it can parse them, but that's it, as far as I know). So, should warn_missing_spec be a dialyzer feature?

The "Erlang-centric" comment meant that I am more than open to re-phrasing the issue more broadly to make it applicable to all the BEAM languages, and to make it worthy a discussion as part of this group. It is about forcing people to write the doc comments, which (in my opinion) one of the forms of documentation. If you still believe this is not the right forum, I would appreciate any pointers in the general direction of the right one. Thanks!

josevalim commented 4 years ago

The same arguments apply to warn_missing_spec, don't they? Erlang compiler does not really care much about the specs (yes, it can parse them, but that's it, as far as I know).

Not really, the compiler parses specs and also validates them. So the compiler gives them their basic structure and low-level semantics, warning for missing types, specs for functions that do not exist, and so on.

On the other hand, Edoc is written as code comments, so they are not parsed at all. In order to emit this warning, the compiler would need to parse comments and attach them to the AST (which could be a breaking change), then parse edocs out of the comments, and then run the requested validation in later stages.

I would agree with your proposal if docs were declared via -doc "foobar"., otherwise there is a non-trivial amount of work and non-conventional changes to make this happen. And it would be something not even used by the Erlang/OTP team, given they use erldoc for most of OTP afaik.

That said, this is really up to the language and how first class they make the docs declaration. Our goal is not really to dictate how languages should declare docs, but rather how to share and access each other docs regardless of how they are declared.