I would like to propose the introduction of extra module attributes that do not generate warnings <https://github.com/elixir-lang/elixir/blob/master/lib/elixir/src/elixir_module.erl#L387>; e.g.:
- `@comment` - `@modulecomment` - `@typecomment` Currently, `@doc`, `@moduledoc` and `@typedoc` are specifically meant to denote documentation related to the public API accessible to read at hexdocs.pm for example. However, at times there is a need to document implementation related matters that are not entirely relevant to the public consumer. What type of algorithm has been used and why? At the heart of this proposal is to argue that there are different degrees of strength in our communication in a code base. My personal perspective from weak to strong: 1. A mere comment: # this does blah 2. A tagged comment: # TODO: blah blah blah 3. dialyzer annotations 4. self documenting code 5. @doc 6. @doc with doctest embedded 7. @moduledoc This ordering will change from organization to organization; but regardless as to that, I think we can all agree that the medium used to express something in our code base is indicative of the importance that such communication is to be heeded to. All forms of commenting have an inherent risk of them being outdated; but surely we assign a greater importance to having `@doc` `@moduledoc` to be in pristine condition as opposed to a mere comment via: `#`. In like fashion, I feel that there is certain documentation of the internal API that can be on the same level of importance as `@doc` and `@moduledoc` except that it is for internal consideration only by the library developers. The introduction of `@comment` etc. as proposed would allow developers to emphasize and help keep track which parts of their internal API need updating in terms of their documentation. `ex_doc` is able to tap into `@doc` etc.; some other tool could likewise tap into these type of module attributes, including some form of `commenttest`. -- 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/e09152e2-b5b9-44d3-9703-70ccc1af42eco%40googlegroups.com.
