# `PhoenixKitWarehouse.Comments`
[🔗](https://github.com/BeamLabEU/phoenix_kit_warehouse/blob/0.4.0/lib/phoenix_kit_warehouse/comments.ex#L1)

Thin isolation layer over `PhoenixKitComments` for every warehouse document
kind.

Consolidates what were 5 near-byte-identical `*_comments.ex` wrapper
modules in Andi (`goods_issue_comments.ex`, `goods_receipt_comments.ex`,
`internal_order_comments.ex`, `supplier_order_comments.ex`,
`inventory_comments.ex`) into one module parameterized by a `kind` atom.
Every function returns a neutral value rather than raising when comments are
unavailable, so callers never special-case it.

## What "unavailable" does and does not cover

`phoenix_kit_comments` is a hard dependency (`mix.exs`, not `optional:`), so
in practice "unavailable" means **installed but disabled** — the
`PhoenixKitComments.enabled?/0` half of `available?/0`. The
`Code.ensure_loaded?/1` half, like the `@compile {:no_warn_undefined, ...}`
below, is always-true residue from treating the package as optional; both are
harmless and left in place, but neither is what makes this module safe.

It does **not** cover version skew. `available?/0` answers "is the module
there and switched on", not "is it new enough": against comments 0.2.6 or
0.2.7 the module is present and `enabled?/0` exists, so `available?/0`
returns `true` and `subscribe/2`, `unsubscribe/2` or the list clause of
`count_comments/2` — all three added in 0.2.8 — would raise. That gap is
closed by the `>= 0.2.8` floor in `mix.exs`, not by any guard here.

`:transfer` was added later (Plan 4/T15) — transfers have no Andi
predecessor, but plug into the same `kind`-parameterized wrapper.

# `kind`

```elixir
@type kind() ::
  :goods_issue
  | :goods_receipt
  | :internal_order
  | :supplier_order
  | :inventory
  | :transfer
```

# `available?`

```elixir
@spec available?() :: boolean()
```

True when the comments module is loadable and enabled. Says nothing about
its *version* — see the moduledoc.

# `count`

```elixir
@spec count(kind(), binary()) :: non_neg_integer()
```

Comment count for one document. Returns 0 when unavailable.

# `counts`

```elixir
@spec counts(kind(), [binary()]) :: %{optional(binary()) => non_neg_integer()}
```

Comment counts for many documents of the same kind, as a `uuid => count`
map. Every requested uuid is present (value 0 when it has no comments).
Returns an empty map when the module is unavailable.

# `resource_type`

```elixir
@spec resource_type(kind()) :: String.t()
```

The comment `resource_type` string used for the given document kind.

# `subscribe`

```elixir
@spec subscribe(kind(), [binary()]) :: :ok
```

Subscribes the calling process to cross-session comment activity for the
given document uuids. No-op when the module is unavailable.

# `unsubscribe`

```elixir
@spec unsubscribe(kind(), [binary()]) :: :ok
```

Unsubscribes the calling process from the given document uuids.

---

*Consult [api-reference.md](api-reference.md) for complete listing*