Don't forget about the documentation!

[José Valim]

Hello everyone,

This is a reminder about the importance of documentation in Elixir projects.

Elixir provides many tools to make documentation easy to write and accessible. However, all those tools and effort will go to waste if we, as a community, don't step up to write good documentation using the appropriate format and guaranteeing it works in our projects.

This does not only apply to open source projects, but to internal projects as well. Once you get the habit of writing documentation, you will find out it not only increases the project quality but it helps with your thought process. For example, if something is hard to document, it is probably doing too much or it is still unclear what its responsibilities are.

Here is a quick refresher:

1. Documentation for Elixir source is written into attributes like @doc (for functions/macros), @moduledoc (for modules) and @typedoc (for types).

2. Documentation is written in Markdown, which is also handy for writing documentation for your READMEs as many websites will render it correctly. We follow Markdown conventions all the way, so, for example, if you are referring to a variable name or a function in your docs, you should write `this_var` and `some_fun/2` (name/arity). By following this format, tools like ExDoc will also generate correct links and so on.

3. You can type `h Enum` or `h Enum.map` to see the documentation for the Enum module and for the Enum.map function directly in the terminal. This works for any compiled module and function.

4. You can also use ExDoc to generate html doc pages for your project. It is also the tool that we use to generate Elixir documentation itself: https://github.com/elixir-lang/ex_doc

5. You can also test and guarantee your documentation is up to date by using doctests. Not everything is "doctest-able" but the majority of functions are.

If you want to see examples of how to write documentation, style and so on, you can always refer to Elixir source itself. Example: https://github.com/elixir-lang/elixir/blob/master/lib/elixir/lib/string.ex

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

[Onorio Catenacci]

Since José brought up doing documentation,  this seems an appropriate point to bring up my recent blog posting. 

http://onor.io/2014/07/16/stupid-doc-tricks-in-elixir/

I would appreciate any thoughts or comments that anyone may care to share on the subject--either here or on the blog.  It just seemed a nice way to accomplish the dual goals of documenting stuff and using constants as opposed to magic numbers.  

I believe that the documentation features built into Elixir make it a natural platform for writing BEAM VM libraries--whether or not those libs are consumed from Erlang or Elixir.  Much easier to document expected parameters, example usage and all those sorts of things the consumer of a library usually wants to see.

By the way, I'm not sure if the markdown should get rendered in werl or not but it's not getting rendered there (on Windows, of course).  I'd guess the answer is probably that it shouldn't get rendered there and I'm going to double check this on my Mac when I get a chance but for whatever it's worth. 

--

Onorio