[erlang-questions] Erlang documentation -- a modest proposal

[José Valim]

> I guess it depends on what you mean by "published Doxygen".
> I was meaning "so-called documentation made available to people outside
> the project generated using Doxygen."
>

I believe one of the main issues with projects like Doxygen is that they
don't make a strong distinction syntax-wise between documentation and code
comments. After all, the two have different targets: the former is for
users of your API, the latter is for readers of your code. And without
having a strong distinction between the two, programmers do not find
themselves in the proper mindset when writing documentation. They write
documentation as if developers were also reading the source code which is
the opposite of what documentation is meant to be.

That's why I dislike the term "doc comments". Is it documentation or is it
a comment?

I have also seen similar confusion in the Ruby community, where there isn't
also a strong distinction between code comment and documentation. I have
heard developers saying "code should be self-documenting" as a
justification for not writing documentation while they probably meant that
"code should be self-explanatory" to imply that excessive code comments may
be a code smell, such as:

# Removes the discount from the tag price

final_price = tag_price - discount


Some languages however, like Python and Clojure, do allow documentation to
be written alongside the source, but they have a strong distinction between
what is documentation and what is a code comment. They also make that
documentation part of the function reflection API, making it easy to
retrieve and format that documentation, even in the language repl.

In any case, reference documentation is only one of aspect of writing
documentation. Regardless if the reference documentation is written at the
source or separately, most libraries also need at least one
guide/tutorial/free-form introduction.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160927/62976cef/attachment.htm>