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 <https://github.com/elixir-lang/elixir/blob/v1.10.4/lib/elixir/lib/module.ex#L1348> makes this distinction explicit; could someone share why this distinction is made? On Sat, Jul 4, 2020 at 2:31 PM Kevin Johnson <[email protected]> wrote: > 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 > <https://groups.google.com/d/msgid/elixir-lang-core/e09152e2-b5b9-44d3-9703-70ccc1af42eco%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- 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/CAAkfbUpOXoyGdEo43WLOf1GQ-SCsdx4%3DMoreu%3D3G0oDQ8uFBzg%40mail.gmail.com.
