defmodule CommendableComments do
  @attributes [
    :modulecomment,
    :comment,
    :typecomment
  ]

  @moduledoc """
  A trivial library that ensures that following module attributes do not throw a warning:
  #{
    @attributes
    |> Enum.map(fn attribute ->
      "  * `@#{attribute}`"
    end)
    |> Enum.join("\n")
  }

  The value of this package is more from the semantical perspective where developers would like
  to document along their code base a variety of implementation and/or domain related matters that
  do not concern any prospective public user of the `API`.

  These could vary from documenting to what type of algorithm was leveraged to realize a particular
  implementation to highlighting the various elements of the conceptual framework that was developed
  under `Domain Driven Design`.

  `@moduledoc`, `@doc` and `@typedoc` have their usage reserved for the public `API` and thus concern
  themselves with the 'how'-usage aspect of things. The usage of the module attributes in this
  package is to anchor the 'why' aspect of things along the relevant parts of the codebase.

  For those who prefer to keep those discussions outside the codebase; inside tickets or various wikis
  they could still embed a direct URL:
  ```elixir
  defmodule A do
    use CommendableComments
    @modulecomment url: link_to_wiki/link_to_jira

    @comment url: link_to_wiki/link_to_jira
    def do_something(a, b) do
      ...
    end
  end
  ```

  In the case of diagrams that are persisted with the project locally, one could express:
  ```elixir
  @comment diagram: path_to_png
  ```
  or in case it is somewhere remote:
  ```elixir
  @comment diagram_url: link_to_online_diagram_in_google_drive
  ```

  All of these annotations are up to your personal discretion. Currently there is no real functionality
  associated with any of this.

  The ultimate ambition of this project is to enrich `ex_doc` to pick up on these attributes. Documentation can thus
  have multiple perspective views; that of a conventional user of your API as well as that of the implementor of your
  organization. Next would be to introduce the concept of `commenttest` that may be beneficial for library developers
  who would still like to document certain functionality that is not relevant for the user of such a library to know
  about.

  Whether or not this will ever come to fruitition will depend on your feedback. If you strongly oppose this concept
  altogether; then even more so I would love to learn from you.
  """

  @doc false
  def attributes, do: @attributes

  defmacro __using__(_) do
    quote do
      CommendableComments.attributes()
      |> Enum.each(fn e ->
        Module.register_attribute(__MODULE__, e, accumulate: true)
      end)
    end
  end
end