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)