docs: wrote initial function an module docs

MikaelFangel · May 8, 2024 · 60db39d · 60db39d
1 parent 2268cfb
commit 60db39d
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 40 deletions.
diff --git a/lib/incident_api.ex b/lib/incident_api.ex
@@ -1,118 +1,142 @@
 defmodule LogpointApi.IncidentApi do
   @moduledoc """
   This module provides an implementation of the Logpoint Incident API.
-
-  ## Modules
-
-   - `TimeRange` : A struct used to represent a time range.
-   - `Incident` : A struct used to represent an incident.
-   - `IncidentComment` : A struct used to represent an incident comment.
-   - `IncidentCommentData` : A struct used to represent incident comment data.
-   - `IncidentIDs` : A struct used to represent incident IDs.
-
-  ## Public Functions
-
-   - `get_incidents/3` : Retrieves incidents within a specified time range.
-   - `get_data_from_incident/3` : Retrieves data from a specific incident.
-   - `get_incident_states/3` : Retrieves incident states within a specified time range.
-   - `get_users/2` : Retrieves user data.
-   - `add_comments/3` : Adds comments to an incident.
-   - `assign_incidents/4` : Assigns incidents to a user.
-   - `resolve_incidents/3` : Resolves incidents.
-   - `reopen_incidents/3` : Reopens incidents.
-   - `close_incidents/3` : Closes incidents.
   """
 
   alias LogpointApi.Credential
-  alias LogpointApi.IncidentApi.{Incident, IncidentComment, IncidentCommentData, IncidentIDs, TimeRange}
 
   defmodule TimeRange do
+    @moduledoc """
+    Struct representing a time range with timestamps in epoch.
+    """
     @derive {Jason.Encoder, only: [:version, :ts_from, :ts_to]}
     defstruct [:ts_from, :ts_to, version: "0.1"]
   end
 
   defmodule Incident do
+    @moduledoc """
+    Struct used to fetch an incident.
+    """
     @derive {Jason.Encoder, only: [:incident_obj_id, :incident_id]}
     defstruct [:incident_obj_id, :incident_id]
   end
 
   defmodule IncidentComment do
+    @moduledoc """
+    Struct to add comments to a particular incident.
+    """
     @derive {Jason.Encoder, only: [:_id, :comments]}
     defstruct _id: "", comments: []
   end
 
   defmodule IncidentCommentData do
+    @moduledoc """
+    Struct to add comments to a list of incidents using the `IncidentComment` struct.
+    """
     @derive {Jason.Encoder, only: [:version, :states]}
     defstruct version: "0.1", states: [%IncidentComment{}]
   end
 
   defmodule IncidentIDs do
+    @moduledoc """
+    Struct that represents a list of incidents.
+    """
     @derive {Jason.Encoder, only: [:version, :incident_ids]}
     defstruct version: "0.1", incident_ids: []
   end
 
+  @doc """
+  Get all incidents within a given time range.
+  """
   @spec get_incidents(String.t(), Credential.t(), TimeRange.t()) ::
           {:ok, map()} | {:error, String.t()}
   def get_incidents(ip, credential, %TimeRange{} = time_range),
     do: get_incident_information(ip, "/incidents", credential, time_range)
 
+  @doc """
+  Get a specific incident and its related data.
+  """
   @spec get_data_from_incident(String.t(), Credential.t(), Incident.t()) ::
           {:ok, map()} | {:error, String.t()}
   def get_data_from_incident(ip, credential, %Incident{} = incident),
     do: get_incident_information(ip, "/get_data_from_incident", credential, incident)
 
+  @doc """
+  Get the states of incidents within a specific time range.
+  """
   @spec get_incident_states(String.t(), Credential.t(), TimeRange.t()) ::
           {:ok, map()} | {:error, String.t()}
   def get_incident_states(ip, credential, %TimeRange{} = time_range),
     do: get_incident_information(ip, "/incident_states", credential, time_range)
 
+  @doc """
+  Get users.
+  """
   @spec get_users(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()}
   def get_users(ip, credential) do
     payload = make_payload(credential)
     make_request(ip, "/get_users", :get, payload)
   end
 
+  @doc """
+  Add comments to a list of incidents.
+  """
   @spec add_comments(String.t(), Credential.t(), IncidentCommentData.t()) ::
           {:ok, map()} | {:error, String.t()}
   def add_comments(ip, credential, %IncidentCommentData{} = incident_comment_data),
     do: update_incident_state(ip, "/add_incident_comment", credential, incident_comment_data)
 
+  @doc """
+  Assign or re-assign a list of incidents.
+  """
   @spec assign_incidents(String.t(), Credential.t(), IncidentIDs.t(), String.t()) ::
           {:ok, map()} | {:error, String.t()}
   def assign_incidents(ip, credential, %IncidentIDs{} = incident_ids, assignee_id) do
     payload = Map.put(incident_ids, :new_assignee, assignee_id)
     update_incident_state(ip, "/assign_incident", credential, payload)
   end
 
+  @doc """
+  Resolve a list of incidents.
+  """
   @spec resolve_incidents(String.t(), Credential.t(), IncidentIDs.t()) ::
           {:ok, map()} | {:error, String.t()}
   def resolve_incidents(ip, credential, %IncidentIDs{} = incident_ids),
     do: update_incident_state(ip, "/resolve_incident", credential, incident_ids)
 
+  @doc """
+  Reopen a list of incidents.
+  """
   @spec reopen_incidents(String.t(), Credential.t(), IncidentIDs.t()) ::
           {:ok, map()} | {:error, String.t()}
   def reopen_incidents(ip, credential, %IncidentIDs{} = incident_ids),
     do: update_incident_state(ip, "/reopen_incident", credential, incident_ids)
 
+  @doc """
+  Close a list of incidents.
+  """
   @spec close_incidents(String.t(), Credential.t(), IncidentIDs.t()) ::
           {:ok, map()} | {:error, String.t()}
   def close_incidents(ip, credential, %IncidentIDs{} = incident_ids),
     do: update_incident_state(ip, "/close_incident", credential, incident_ids)
 
+  @doc false
   @spec update_incident_state(String.t(), String.t(), Credential.t(), map()) ::
           {:ok, map()} | {:error, String.t()}
   defp update_incident_state(ip, path, credential, request_data) do
     payload = make_payload(credential, request_data)
     make_request(ip, path, :post, payload)
   end
 
+  @doc false
   @spec get_incident_information(String.t(), String.t(), Credential.t(), map()) ::
           {:ok, map()} | {:error, String.t()}
   defp get_incident_information(ip, path, credential, request_data) do
     payload = make_payload(credential, request_data)
     make_request(ip, path, :get, payload)
   end
 
+  @doc false
   @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)
@@ -132,9 +156,11 @@ defmodule LogpointApi.IncidentApi do
     end
   end
 
+  @doc false
   @spec build_url(String.t(), String.t()) :: String.t()
   defp build_url(ip, path), do: "https://" <> ip <> path
 
+  @doc false
   @spec make_payload(Credential.t(), map()) :: String.t()
   defp make_payload(%Credential{} = credential, request_data) do
     %{
@@ -145,6 +171,7 @@ defmodule LogpointApi.IncidentApi do
     |> Jason.encode!()
   end
 
+  @doc false
   @spec make_payload(Credential.t()) :: String.t()
   defp make_payload(%Credential{} = credential) do
     %{

diff --git a/lib/logpoint_api.ex b/lib/logpoint_api.ex
@@ -1,5 +1,10 @@
 defmodule LogpointApi do
+  @moduledoc false
+
   defmodule Credential do
+    @moduledoc """
+    Struct representing credentials used for authorization.
+    """
     defstruct [:username, :secret_key]
   end
 end
diff --git a/lib/search_api.ex b/lib/search_api.ex
@@ -1,25 +1,6 @@
 defmodule LogpointApi.SearchApi do
   @moduledoc """
   This module provides an implementation of the Logpoint search API.
-
-  ## Modules
-
-   - `Query` : A struct used to represent a search query.
-   - `SearchID` : A struct used to represent a search ID.
-
-  ## Constants
-
-   - `@allowed_types` : A list of allowed types for data retrieval.
-
-  ## Public Functions
-
-   - `get_user_timezone/2` : Retrieves user timezone data.
-   - `get_logpoints/2` : Retrieves logpoints data.
-   - `get_repos/2` : Retrieves repositories data.
-   - `get_devices/2` : Retrieves devices data.
-   - `get_livesearches/2` : Retrieves live searches data.
-   - `get_search_id/3` : Creates a search in Logpoint and returns the JSON object.
-   - `get_search_result/3` : Retrieves search results for a given search ID.
   """
 
   alias LogpointApi.Credential
@@ -28,45 +9,73 @@ defmodule LogpointApi.SearchApi do
   @allowed_types ["user_preference", "loginspects", "logpoint_repos", "devices", "livesearches"]
 
   defmodule Query do
+    @moduledoc """
+    Struct representing a Logpoint search query.
+    """
     @derive {Jason.Encoder, only: [:query, :time_range, :limit, :repos]}
     defstruct [:query, :time_range, :limit, :repos]
   end
 
   defmodule SearchID do
+    @moduledoc """
+    Struct representing a search id.
+    """
     @derive {Jason.Encoder, only: [:search_id]}
     defstruct [:search_id]
   end
 
+  @doc """
+  Get the current users time zone information.
+  """
   @spec get_user_timezone(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()}
   def get_user_timezone(ip, credential),
     do: get_allowed_data(ip, credential, "user_preference")
 
+  @doc """
+  Get all logpoints of a Logpoint instance.
+  """
   @spec get_logpoints(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()}
   def get_logpoints(ip, credential),
     do: get_allowed_data(ip, credential, "loginspects")
 
+  @doc """
+  Get the repos of an instance.
+  """
   @spec get_repos(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()}
   def get_repos(ip, credential),
     do: get_allowed_data(ip, credential, "logpoint_repos")
 
+  @doc """
+  Get the devices of the instance.
+  """
   @spec get_devices(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()}
   def get_devices(ip, credential),
     do: get_allowed_data(ip, credential, "devices")
 
+  @doc """
+  Get all live search on a machine.
+  """
   @spec get_livesearches(String.t(), Credential.t()) :: {:ok, map()} | {:error, String.t()}
   def get_livesearches(ip, credential),
     do: get_allowed_data(ip, credential, "livesearches")
 
+  @doc """
+  Create a search and get its search id.
+  """
   @spec get_search_id(String.t(), Credential.t(), Query.t()) ::
           {:ok, map()} | {:error, String.t()}
   def get_search_id(ip, credential, %Query{} = query),
     do: get_search_logs(ip, credential, query)
 
+  @doc """
+  Retrieve the search result of a specific search id.
+  """
   @spec get_search_result(String.t(), Credential.t(), SearchID.t()) ::
           {:ok, map()} | {:error, String.t()}
   def get_search_result(ip, credential, %SearchID{} = search_id),
     do: get_search_logs(ip, credential, search_id)
 
+  @doc false
   @spec make_request(String.t(), String.t(), String.t()) :: {:ok, map()} | {:error, String.t()}
   defp make_request(ip, path, payload) do
     url = build_url(ip, path)
@@ -86,21 +95,25 @@ defmodule LogpointApi.SearchApi do
     end
   end
 
+  @doc false
   @spec build_url(String.t(), String.t()) :: String.t()
   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()}
   defp get_allowed_data(ip, credential, type) when type in @allowed_types do
     payload = build_payload(credential, %{"type" => type})
     make_request(ip, "/getalloweddata", payload)
   end
 
+  @doc false
   @spec get_search_logs(String.t(), Credential.t(), map()) :: {:ok, map()} | {:error, String.t()}
   defp get_search_logs(ip, credential, request_data) do
     payload = build_payload(credential, %{"requestData" => Jason.encode!(request_data)})
     make_request(ip, "/getsearchlogs", payload)
   end
 
+  @doc false
   @spec build_payload(Credential.t(), map()) :: String.t()
   defp build_payload(%Credential{} = credential, data) do
     Map.merge(