Add docs #20

szakhlypa · 2022-10-10T10:05:12Z

No description provided.

Signed-off-by: Sergey Zakhlypa <[email protected]>

coveralls · 2022-10-10T10:06:30Z

Pull Request Test Coverage Report for Build 9c514c8f0bb208de207b0792d7f8162eb9527c96-PR-20

3 of 3 (100.0%) changed or added relevant lines in 3 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage remained the same at 90.506%

Totals
Change from base Build 602e78a22ed45d6731f7d5d4d4f59914a6d60417:	0.0%
Covered Lines:	286
Relevant Lines:	316

💛 - Coveralls

rbino · 2022-10-18T11:10:31Z

lib/astarte/client.ex

-  @moduledoc """
-  Documentation for `Astarte.Client`.
-  """
+  @moduledoc false


Let's plan to remove this module in a following MR since it's currently useless

rbino · 2022-10-18T11:11:51Z

lib/astarte/client/api_error.ex

+  This struct is designed to provide information needed to effectively log and maybe respond
+  to an error.


-> This struct is designed to provide relevant information about the error.

rbino · 2022-10-18T11:12:32Z

lib/astarte/client/appengine.ex

+  @moduledoc """
+  Module to configure communication with Astarte AppEngine API.
+
+  Most applications would want to use AppEngine to interact with devices, stream and receive data, and oversee their fleet.


oversee their fleet -> interact with the fleet

rbino · 2022-10-18T11:13:02Z

lib/astarte/client/appengine.ex

-  alias __MODULE__
-  alias Astarte.Client.Credentials
+  @doc """
+  Returns configured `Astarte.Client.AppEngine` struct.


-> a configured

rbino · 2022-10-18T11:13:24Z

lib/astarte/client/appengine.ex


-  @jwt_expiry 5 * 60
+  This function receives Astarte base API URL and name of the realm alongside authentication options


receives the Astarte [...] and the name of [...]

rbino · 2022-10-18T11:24:24Z

lib/astarte/client/appengine/devices.ex

+  @doc """
+  Unset a value on a given endpoint path, path is also deleted.
+
+  Interface should be an individual server owned property interface and to support unset.


[...] interface that supports unsets.

rbino · 2022-10-18T11:26:26Z

lib/astarte/client/appengine/devices.ex

+    It must be a ISO 8601 valid timestamp.
+    This option is mutually exclusive with `:since`.
+
+    * `:to` - query all values up to a certain timestamp.


up to and including/excluding (not sure what is the actual behaviour tbh)

rbino · 2022-10-18T11:27:37Z

lib/astarte/client/appengine/devices.ex

+
+    * `:to` - query all values up to a certain timestamp.
+    It must be a ISO 8601 valid timestamp.
+    If `:since` and `:since_after` are not specified first entry date is assumed by default.


Not sure if we need this line

rbino · 2022-10-18T11:27:52Z

lib/astarte/client/appengine/devices.ex

+    It must be a ISO 8601 valid timestamp.
+    If `:since` and `:since_after` are not specified first entry date is assumed by default.
+
+    * `:limit` - limit number of retrieved data production entries to `:limit`.


limit the number [...]

rbino · 2022-10-18T11:29:07Z

lib/astarte/client/appengine/devices.ex

+
+    * `:query` - list of query params
+
+  ## Query options


In all the examples, don't use the atom when using it as value, i.e. remove the : in front.
For example:
query all values since a certain timestamp (all entries where timestamp >= :since
becomes
query all values since a certain timestamp (all entries where timestamp >= since

And so on for all the others

atsetilam · 2022-10-18T12:41:19Z

lib/astarte/client/appengine.ex

+
+  One of `:jwt` and `:private_key` options is required.
+
+    * `:jwt` - JWT for Bearer authentication, if used `:private_key` and `:jwt_opts` are ignored


JWT for Bearer authentication ; if used, :private_key and :jwt_opts are ignored

atsetilam · 2022-10-18T12:42:32Z

lib/astarte/client/appengine.ex

+
+    * `:jwt` - JWT for Bearer authentication, if used `:private_key` and `:jwt_opts` are ignored
+
+    * `:private_key` - will be used to generate JWT, this option is mutually exclusive


private_key` - will be used to generate JWT ; this option is mutually exclusive

atsetilam · 2022-10-18T12:43:39Z

lib/astarte/client/appengine.ex

+    * `:jwt` - JWT for Bearer authentication, if used `:private_key` and `:jwt_opts` are ignored
+
+    * `:private_key` - will be used to generate JWT, this option is mutually exclusive
+    with `:jwt`, if the latter is used, this option will be ignored.


with :jwt . If the latter is used, this option will be ignored.

atsetilam · 2022-10-18T12:44:24Z

lib/astarte/client/appengine.ex

+    * `:private_key` - will be used to generate JWT, this option is mutually exclusive
+    with `:jwt`, if the latter is used, this option will be ignored.
+
+    * `:jwt_opts` - will add additional JWT claims to generated JWT, this option is mutually exclusive


will add additional JWT claims to the generated JWT ; this option is mutually exclusive

atsetilam · 2022-10-18T12:44:49Z

lib/astarte/client/appengine.ex

+    with `:jwt`, if the latter is used, this option will be ignored.
+
+    * `:jwt_opts` - will add additional JWT claims to generated JWT, this option is mutually exclusive
+    with `:jwt`, if the latter is used, this option will be ignored.


with :jwt . If the latter is used, this option will be ignored.

atsetilam · 2022-10-18T12:47:15Z

lib/astarte/client/appengine/devices.ex

+  Returns a list of interfaces supported by a certain device.
+
+  Interfaces that are not reported by the device are not reported here.
+  If a device stops to advertise a certain interface, it should be retrived from a different API,


If a device stops to advertise a certain interface, it should be retrived from a different API .

atsetilam · 2022-10-18T12:47:30Z

lib/astarte/client/appengine/devices.ex

+
+  Interfaces that are not reported by the device are not reported here.
+  If a device stops to advertise a certain interface, it should be retrived from a different API,
+  same applies for older versions of a certain interface.


The same applies for older versions of a certain interface.

atsetilam · 2022-10-18T12:49:28Z

lib/astarte/client/appengine/devices.ex

@@ -57,6 +103,18 @@ defmodule Astarte.Client.AppEngine.Devices do
    end
  end

+  @doc """
+  Returns a values snapshot for a given interface without `:path` option, otherwise


Returns a value s snapshot for a given interface without :path option, otherwise

or

Returns a snapshot of values for a given interface without :path option, otherwise

atsetilam · 2022-10-18T12:50:33Z

lib/astarte/client/appengine/devices.ex

+  @doc """
+  Update a property value on a given endpoint path.
+
+  Interface should be an individual server owned property interface.


The interface should be an individual server owned property interface.

atsetilam · 2022-10-18T12:51:56Z

lib/astarte/client/appengine/devices.ex

@@ -106,6 +176,36 @@ defmodule Astarte.Client.AppEngine.Devices do
    end
  end

+  @doc """
+  Returns values for a given datastream interface.


It returns values for a given datastream interface.

atsetilam · 2022-10-18T12:53:01Z

lib/astarte/client/appengine/devices.ex

+
+    * `:to` - query all values up to a certain timestamp.
+    It must be a ISO 8601 valid timestamp.
+    If `:since` and `:since_after` are not specified first entry date is assumed by default.


[...] , the specified first entry date is assumed by default.

atsetilam · 2022-10-18T15:14:24Z

lib/astarte/client/credentials.ex

  def append_housekeeping_claim(%Credentials{} = credentials, claim) when is_binary(claim) do
    append_claim(credentials, "a_ha", claim)
  end

+  @doc """
+  Appends claim for Realm Management API


It appends a claim

or

It appends claims

atsetilam · 2022-10-18T15:14:34Z

lib/astarte/client/credentials.ex

  def append_realm_management_claim(%Credentials{} = credentials, claim) when is_binary(claim) do
    append_claim(credentials, "a_rma", claim)
  end

+  @doc """
+  Appends claim for Pairing API


It appends a claim

or

It appends claims

atsetilam · 2022-10-18T15:14:41Z

lib/astarte/client/credentials.ex

  def append_pairing_claim(%Credentials{} = credentials, claim) when is_binary(claim) do
    append_claim(credentials, "a_pa", claim)
  end

+  @doc """
+  Appends claim for AppEngine API


It appends a claim

or

It appends claims

atsetilam · 2022-10-18T15:14:47Z

lib/astarte/client/credentials.ex

  def append_appengine_claim(%Credentials{} = credentials, claim) when is_binary(claim) do
    append_claim(credentials, "a_aea", claim)
  end

+  @doc """
+  Appends claim for Astarte Channels


It appends a claim

or

It appends claims

atsetilam · 2022-10-18T15:14:58Z

lib/astarte/client/credentials.ex

  def append_channels_claim(%Credentials{} = credentials, claim) when is_binary(claim) do
    append_claim(credentials, "a_ch", claim)
  end

+  @doc """
+  Appends claim for Flow API


It appends a claim

or

It appends claims

atsetilam · 2022-10-18T15:39:04Z

lib/astarte/client/credentials.ex

@@ -144,6 +293,17 @@ defmodule Astarte.Client.Credentials do
    %{credentials | claims: updated_claims}
  end

+  @doc """
+  Sets expiry used to generate expiration time claim.


It sets an expiry used to generate an/the expiration time claim.

atsetilam · 2022-10-18T15:48:31Z

lib/astarte/client/housekeeping.ex


-  @jwt_expiry 5 * 60
+  This function receives Astarte base API URL alongside authentication options
+  and returns configured `Astarte.Client.Housekeeping` struct.


and returns a configured [...]

atsetilam · 2022-10-18T15:48:46Z

lib/astarte/client/housekeeping.ex


-  @jwt_expiry 5 * 60
+  This function receives Astarte base API URL alongside authentication options


This function receives the Astarte base API URL [...]

atsetilam · 2022-10-18T19:04:34Z

lib/astarte/client/housekeeping.ex

+  Housekeeping is the equivalent of a superadmin API.
+  It allows to manage and create realms, perform cluster-wide maintenance actions.
+  This API is usually accessible only to system administrators, and is not meant for the average user of Astarte,
+  which should refer to `Astarte.Client.RealmManagement` instead.


who should refer [...]

atsetilam · 2022-10-18T19:07:08Z

lib/astarte/client/housekeeping.ex

+  This function receives Astarte base API URL alongside authentication options
+  and returns configured `Astarte.Client.Housekeeping` struct.
+
+  ## Options


Rework punctuation in this section as per above comments.

atsetilam · 2022-10-18T19:08:18Z

lib/astarte/client/housekeeping/realms.ex

+
+    * `:datacenter_replication_factors` - uses `NetworkTopologyStrategy` replication strategy
+    and allows to define the number of replicas for each data center.
+    This option is mutually exclusive with `:replication_factor`,


[...] with :replication_factor ;

atsetilam · 2022-10-18T19:08:54Z

lib/astarte/client/housekeeping/realms.ex

+
+    * `:replication_factor` - uses `SimpleStrategy` replication strategy
+    and allows to define the number of replicas for a single datacenter.
+    This option is mutually exclusive with `:datacenter_replication_factors`,


[see above]

atsetilam · 2022-10-18T19:10:47Z

lib/astarte/client/pairing.ex

  @enforce_keys [:http_client]
  defstruct @enforce_keys

  @type t :: %__MODULE__{
          http_client: Tesla.Client.t()
        }

-  alias Astarte.Client.Credentials
+  @doc """
+  Returns configured `Astarte.Client.Pairing` struct.


Returns a configured [...]

atsetilam · 2022-10-18T19:12:35Z

lib/astarte/client/housekeeping/realms.ex

@@ -110,6 +147,10 @@ defmodule Astarte.Client.Housekeeping.Realms do
    end
  end

+  @doc """
+  Returns a realm's configuration.


Capitalise Realm (e.g. https://docs.astarte-platform.org/latest/020-components.html#realm-management)

atsetilam · 2022-10-18T19:13:37Z

lib/astarte/client/pairing.ex


-  @jwt_expiry 5 * 60
+  This function receives Astarte base API URL and name of the realm alongside authentication options


receives the Astarte [...] and the name of the Realm

atsetilam · 2022-10-18T19:14:14Z

lib/astarte/client/pairing.ex


-  @jwt_expiry 5 * 60
+  This function receives Astarte base API URL and name of the realm alongside authentication options
+  and returns configured `Astarte.Client.Pairing` struct.


and returns a configured [...]

atsetilam · 2022-10-18T19:14:38Z

lib/astarte/client/pairing.ex

+  This function receives Astarte base API URL and name of the realm alongside authentication options
+  and returns configured `Astarte.Client.Pairing` struct.
+
+  ## Options


Rework punctuation in this section as per above comments.

atsetilam · 2022-10-18T19:16:35Z

lib/astarte/client/pairing/agent.ex

+  @doc """
+  Register a device, obtaining its credentials secret.
+
+  The registration can be repeated as long as the device didn't request any credentials.


I would avoid contractions.

[...] the device did not request [...]

atsetilam · 2022-10-18T19:20:08Z

lib/astarte/client/pairing/agent.ex

+  @doc """
+  Unregister a device.
+
+  This makes it possible to register it again, even if it already has requested its credentials.


This allows registering the device again, even if it has already requested its credentials.

atsetilam · 2022-10-18T19:23:13Z

lib/astarte/client/realm_management.ex

-  alias __MODULE__
-  alias Astarte.Client.Credentials
+  @doc """
+  Returns configured `Astarte.Client.RealmManagement` struct.


Returns a configured [...]

atsetilam · 2022-10-18T19:23:31Z

lib/astarte/client/realm_management.ex


-  @jwt_expiry 5 * 60
+  This function receives Astarte base API URL and name of the realm alongside authentication options


receives the Astarte [...] and the name of the Realm

atsetilam · 2022-10-18T19:23:50Z

lib/astarte/client/realm_management.ex


-  @jwt_expiry 5 * 60
+  This function receives Astarte base API URL and name of the realm alongside authentication options
+  and returns configured `Astarte.Client.RealmManagement` struct.


and returns a configured [...]

atsetilam · 2022-10-18T19:24:20Z

lib/astarte/client/realm_management.ex

+  This function receives Astarte base API URL and name of the realm alongside authentication options
+  and returns configured `Astarte.Client.RealmManagement` struct.
+
+  ## Options


Rework punctuation in this section as per above comments.

atsetilam · 2022-10-18T19:25:06Z

lib/astarte/client/realm_management/interfaces.ex

@@ -32,6 +48,15 @@ defmodule Astarte.Client.RealmManagement.Interfaces do
    end
  end

+  @doc """
+  Returns the list of all major versions for given interface.


[...] for a given interface.

atsetilam · 2022-10-18T19:26:22Z

lib/astarte/client/realm_management/interfaces.ex

+  Update an existing interface.
+
+  Replaces an existing interface with a given major version with a new one
+  (that must have same major version and a higher minor version).


(that must have the same major version [...]

atsetilam · 2022-10-18T19:26:55Z

lib/astarte/client/realm_management/realm_config.ex

  alias Astarte.Client.{APIError, RealmManagement}

+  @doc """
+  Returns the auth configuration of the realm.


Capitalise Realm.

atsetilam · 2022-10-18T19:27:07Z

lib/astarte/client/realm_management/realm_config.ex

@@ -32,6 +41,10 @@ defmodule Astarte.Client.RealmManagement.RealmConfig do
    end
  end

+  @doc """
+  Installs an auth configuration for the realm.


Capitalise Realm.

atsetilam · 2022-10-18T19:27:39Z

lib/astarte/client/realm_management/triggers.ex

  alias Astarte.Client.{APIError, RealmManagement}

+  @doc """
+  Returns the list of all installed triggers.


all the installed triggers.

atsetilam · 2022-10-18T19:28:17Z

lib/astarte/client/realm_management/triggers.ex

+  @doc """
+  Create a new trigger using provided configuration.
+
+  Trigger validation is performed before installation, if trigger configuration is not valid or


Trigger validation is performed before installation ; if trigger

atsetilam · 2022-10-18T19:28:57Z

lib/astarte/client/realm_management/triggers.ex

+  Create a new trigger using provided configuration.
+
+  Trigger validation is performed before installation, if trigger configuration is not valid or
+  a trigger with the same name already exists an error is reported.


a trigger with the same name already exists , an error is reported.

szakhlypa added 17 commits October 10, 2022 11:48

Add ex_doc dependency

19a4d7e

Signed-off-by: Sergey Zakhlypa <[email protected]>

Clean Astarte.Client module docs

99ccd77

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.APIError

2035822

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.AppEngine module

e6edf5c

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.AppEngine.Devices module

1d4ef53

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.AppEngine.Groups module

3e3e240

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.AppEngine.Stats module

07be296

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.Housekeeping module

b6e6c35

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.Housekeeping.Realms module

01f129f

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.Pairing module

aaf623f

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.Pairing.Agent module

7ffca2b

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.RealmManagement module

f133ed6

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.RealmManagement.Interfaces module

ee602dd

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.RealmManagement.RealmConfig module

78e5f1c

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.RealmManagement.Triggers module

f87f706

Signed-off-by: Sergey Zakhlypa <[email protected]>

Docs: group and nest modules

2f58729

Signed-off-by: Sergey Zakhlypa <[email protected]>

Add docs for Astarte.Client.Credentials

9c514c8

Signed-off-by: Sergey Zakhlypa <[email protected]>

rbino requested changes Oct 18, 2022

View reviewed changes

atsetilam reviewed Oct 18, 2022

View reviewed changes

		This struct is designed to provide information needed to effectively log and maybe respond
		to an error.


		@jwt_expiry 5 * 60
		This function receives Astarte base API URL and name of the realm alongside authentication options


		One of `:jwt` and `:private_key` options is required.

		* `:jwt` - JWT for Bearer authentication, if used `:private_key` and `:jwt_opts` are ignored


		* `:jwt` - JWT for Bearer authentication, if used `:private_key` and `:jwt_opts` are ignored

		* `:private_key` - will be used to generate JWT, this option is mutually exclusive

Add docs #20

Are you sure you want to change the base?

Add docs #20

Conversation

szakhlypa commented Oct 10, 2022

coveralls commented Oct 10, 2022

Pull Request Test Coverage Report for Build 9c514c8f0bb208de207b0792d7f8162eb9527c96-PR-20

💛 - Coveralls

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 • edited Loading

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 • edited Loading

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsetilam Oct 18, 2022 •

edited

Loading

atsetilam Oct 18, 2022 •

edited

Loading

atsetilam Oct 18, 2022 •

edited

Loading

atsetilam Oct 18, 2022 •

edited

Loading

atsetilam Oct 18, 2022 •

edited

Loading

atsetilam Oct 18, 2022 •

edited

Loading

atsetilam Oct 18, 2022 •

edited

Loading