From 0cc0f64579c4d323c8e41a5a84d27515fdd6485f Mon Sep 17 00:00:00 2001
From: Mikael Fangel <34864484+MikaelFangel@users.noreply.github.com>
Date: Fri, 10 May 2024 22:43:28 +0200
Subject: [PATCH] docs: added type docs for structs

---
 lib/incident_api.ex | 20 +++++++++++++-------
 lib/logpoint_api.ex |  3 ++-
 lib/search_api.ex   | 14 +++++++++++---
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/lib/incident_api.ex b/lib/incident_api.ex
index 79411cd..ffcddd7 100644
--- a/lib/incident_api.ex
+++ b/lib/incident_api.ex
@@ -6,41 +6,46 @@ defmodule LogpointApi.IncidentApi do
   alias LogpointApi.Credential
 
   defmodule TimeRange do
-    @moduledoc """
+    @typedoc """
     Struct representing a time range with timestamps in epoch.
     """
+    @type t :: %__MODULE__{ts_from: Number.t(), ts_to: Number.t(), version: String.t()}
     @derive {Jason.Encoder, only: [:version, :ts_from, :ts_to]}
     defstruct [:ts_from, :ts_to, version: "0.1"]
   end
 
   defmodule Incident do
-    @moduledoc """
+    @typedoc """
     Struct used to fetch an incident.
     """
+    @type t :: %__MODULE__{incident_obj_id: String.t(), incident_id: String.t()}
     @derive {Jason.Encoder, only: [:incident_obj_id, :incident_id]}
     defstruct [:incident_obj_id, :incident_id]
   end
 
   defmodule IncidentComment do
-    @moduledoc """
+    @typedoc """
     Struct to add comments to a particular incident.
     """
+    @type t :: %__MODULE__{_id: String.t(), comments: list()}
     @derive {Jason.Encoder, only: [:_id, :comments]}
     defstruct _id: "", comments: []
   end
 
   defmodule IncidentCommentData do
-    @moduledoc """
+    @typedoc """
     Struct to add comments to a list of incidents using the `IncidentComment` struct.
     """
+    @type t :: %__MODULE__{version: String.t(), states: list()}
     @derive {Jason.Encoder, only: [:version, :states]}
     defstruct version: "0.1", states: [%IncidentComment{}]
   end
 
   defmodule IncidentIDs do
-    @moduledoc """
+    @typedoc """
     Struct that represents a list of incidents.
     """
+    @type t :: %__MODULE__{version: String.t(), incident_ids: list()}
     @derive {Jason.Encoder, only: [:version, :incident_ids]}
     defstruct version: "0.1", incident_ids: []
   end
@@ -137,7 +142,8 @@ defmodule LogpointApi.IncidentApi do
   end
 
   @doc false
-  @spec make_request(String.t(), String.t(), atom(), String.t()) :: {:ok, map()} | {:error, String.t()}
+  @spec make_request(String.t(), String.t(), atom(), String.t()) ::
+          {:ok, map()} | {:error, String.t()}
   defp make_request(ip, path, method, payload) do
     url = build_url(ip, path)
     headers = [{"Content-Type", "application/json"}]
@@ -176,7 +182,7 @@ defmodule LogpointApi.IncidentApi do
   defp make_payload(%Credential{} = credential) do
     %{
       "username" => credential.username,
-      "secret_key" => credential.secret_key,
+      "secret_key" => credential.secret_key
     }
     |> Jason.encode!()
   end
diff --git a/lib/logpoint_api.ex b/lib/logpoint_api.ex
index 449fb2d..57ff874 100644
--- a/lib/logpoint_api.ex
+++ b/lib/logpoint_api.ex
@@ -2,9 +2,10 @@ defmodule LogpointApi do
   @moduledoc false
 
   defmodule Credential do
-    @moduledoc """
+    @typedoc """
     Struct representing credentials used for authorization.
     """
+    @type t :: %__MODULE__{username: String.t(), secret_key: String.t()}
     defstruct [:username, :secret_key]
   end
 end
diff --git a/lib/search_api.ex b/lib/search_api.ex
index ae6fc9b..493cffe 100644
--- a/lib/search_api.ex
+++ b/lib/search_api.ex
@@ -9,17 +9,24 @@ defmodule LogpointApi.SearchApi do
   @allowed_types ["user_preference", "loginspects", "logpoint_repos", "devices", "livesearches"]
 
   defmodule Query do
-    @moduledoc """
+    @typedoc """
     Struct representing a Logpoint search query.
     """
+    @type t :: %__MODULE__{
+            query: String.t(),
+            time_range: list(),
+            limit: Number.t(),
+            repos: list()
+          }
     @derive {Jason.Encoder, only: [:query, :time_range, :limit, :repos]}
     defstruct [:query, :time_range, :limit, :repos]
   end
 
   defmodule SearchID do
-    @moduledoc """
+    @typedoc """
     Struct representing a search id.
     """
+    @type t :: %__MODULE__{search_id: String.t()}
     @derive {Jason.Encoder, only: [:search_id]}
     defstruct [:search_id]
   end
@@ -100,7 +107,8 @@ defmodule LogpointApi.SearchApi do
   defp build_url(ip, path), do: "https://" <> ip <> path
 
   @doc false
-  @spec get_allowed_data(String.t(), Credential.t(), String.t()) :: {:ok, map()} | {:error, String.t()}
+  @spec get_allowed_data(String.t(), Credential.t(), String.t()) ::
+          {:ok, map()} | {:error, String.t()}
   defp get_allowed_data(ip, credential, type) when type in @allowed_types do
     payload = build_payload(credential, %{"type" => type})
     make_request(ip, "/getalloweddata", payload)