@comment and @modulecomment

[Kevin Johnson]

I would like to propose the introduction of extra module attributes that do not generate warnings; 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`.

[Kevin Johnson]

I have been exploring this idea from a library perspective and to my surprise, there is a difference in behaviour when you register a module attribute with `accumulate: false` vs `accumulate: true`.

When using `accumulate: false`, a warning gets emitted(`warning: module attribute @modulecomment was set but never used`) when you do not use that module attribute anywhere whereas using `accumulate: true`, a warning does not get emitted(even though you do not use that module attribute anywhere).

The source code makes this distinction explicit; could someone share why this distinction is made?

--
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-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/e09152e2-b5b9-44d3-9703-70ccc1af42eco%40googlegroups.com.