doc and other minor fixes

4 files changed, 74 insertions, 68 deletions

diff --git a/lib/polyjuice/client/account.ex b/lib/polyjuice/client/account.ex
index d7b8d0d..cd99f01 100644
--- a/lib/polyjuice/client/account.ex
+++ b/lib/polyjuice/client/account.ex
@@ -18,16 +18,19 @@ defmodule Polyjuice.Client.Account do
   """
 
   @doc """
-  Get the data on an account
-  `event_type` : type of event queried
-  `user_id`: User concerned by the event
+  Get the data on an account.
+
+  `user_id` is the user whose data is to be queried; if not specified, defaults
+  to the user represented by `client_api`. `event_type` is the type of event
+  queried.
   """
   @spec get_data(
           client_api :: Polyjuice.Client.API.t(),
           user_id :: String.t() | nil,
           event_type :: String.t()
         ) :: {:ok, map()} | any
-  def get_data(client_api, user_id \\ nil, event_type) do
+  def get_data(client_api, user_id \\ nil, event_type)
+      when (is_binary(user_id) or user_id == nil) and is_binary(event_type) do
     Polyjuice.Client.API.call(
       client_api,
       %Polyjuice.Client.Endpoint.GetAccountData{
@@ -38,24 +41,26 @@ defmodule Polyjuice.Client.Account do
   end
 
   @doc """
-  Put the data on an account
-  `event_type` : type of event requiring modifications
-  `changes`: New changes
-  `user_id`: User concerned by the event
+  Put the data on an account.
+
+  `user_id` is the user whose data is to be set; if not specified, defaults to
+  the user represented by `client_api`. `event_type` is type of event to set and
+  `data` is the new data.
   """
   @spec put_data(
           client_api :: Polyjuice.Client.API.t(),
           user_id :: String.t() | nil,
           event_type :: String.t(),
-          changes :: Map.t()
+          data :: Map.t()
         ) :: {:ok} | any
-  def put_data(client_api, user_id \\ nil, event_type, changes) do
+  def put_data(client_api, user_id \\ nil, event_type, data)
+      when (is_binary(user_id) or user_id == nil) and is_binary(event_type) and is_map(data) do
     Polyjuice.Client.API.call(
       client_api,
       %Polyjuice.Client.Endpoint.PutAccountData{
         user_id: user_id || Polyjuice.Client.API.get_user_and_device(client_api) |> elem(0),
         type: event_type,
-        account_data: changes
+        account_data: data
       }
     )
   end
diff --git a/lib/polyjuice/client/endpoint/get_rooms_state.ex b/lib/polyjuice/client/endpoint/get_rooms_state.ex
index f274892..b2cbae8 100644
--- a/lib/polyjuice/client/endpoint/get_rooms_state.ex
+++ b/lib/polyjuice/client/endpoint/get_rooms_state.ex
@@ -1,4 +1,4 @@
-# Copyright 2020 Hubert Chathi <hubert@uhoreg.ca>
+# Copyright 2020 Pierre de Lacroix <pierre@pdelacroix.com>
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
diff --git a/lib/polyjuice/client/room.ex b/lib/polyjuice/client/room.ex
index 5dbf80d..7ecc02e 100644
--- a/lib/polyjuice/client/room.ex
+++ b/lib/polyjuice/client/room.ex
@@ -57,18 +57,18 @@ defmodule Polyjuice.Client.Room do
   """
   @spec send_message(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           msg :: map | Polyjuice.Client.MsgBuilder.MsgData.t()
         ) :: {:ok, String.t()} | any
-  def send_message(client_api, room, msg) when is_binary(room) do
-    Polyjuice.Client.API.room_queue(client_api, room, fn ->
+  def send_message(client_api, room_id, msg) when is_binary(room_id) do
+    Polyjuice.Client.API.room_queue(client_api, room_id, fn ->
       cond do
         Polyjuice.Client.MsgBuilder.MsgData.impl_for(msg) != nil ->
           Polyjuice.Client.API.call(
             client_api,
             %Polyjuice.Client.Endpoint.PutRoomsSend{
               txn_id: Polyjuice.Client.API.transaction_id(client_api),
-              room: room,
+              room: room_id,
               event_type: "m.room.message",
               message: Polyjuice.Client.MsgBuilder.to_message(msg)
             }
@@ -79,7 +79,7 @@ defmodule Polyjuice.Client.Room do
             client_api,
             %Polyjuice.Client.Endpoint.PutRoomsSend{
               txn_id: Polyjuice.Client.API.transaction_id(client_api),
-              room: room,
+              room: room_id,
               event_type: "m.room.message",
               message: msg
             }
@@ -96,18 +96,18 @@ defmodule Polyjuice.Client.Room do
   """
   @spec send_event(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           event_type :: String.t(),
           event :: map
         ) :: {:ok, String.t()} | any
-  def send_event(client_api, room, event_type, event)
-      when is_binary(event_type) and is_map(event) and is_binary(room) do
-    Polyjuice.Client.API.room_queue(client_api, room, fn ->
+  def send_event(client_api, room_id, event_type, event)
+      when is_binary(event_type) and is_map(event) and is_binary(room_id) do
+    Polyjuice.Client.API.room_queue(client_api, room_id, fn ->
       Polyjuice.Client.API.call(
         client_api,
         %Polyjuice.Client.Endpoint.PutRoomsSend{
           txn_id: Polyjuice.Client.API.transaction_id(client_api),
-          room: room,
+          room: room_id,
           event_type: event_type,
           message: event
         }
@@ -120,18 +120,18 @@ defmodule Polyjuice.Client.Room do
   """
   @spec send_state_event(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           event_type :: String.t(),
           state_key :: String.t(),
           event :: map
         ) :: {:ok, String.t()} | any
-  def send_state_event(client_api, room, event_type, state_key \\ "", event)
-      when is_binary(event_type) and is_binary(state_key) and is_map(event) and is_binary(room) do
-    Polyjuice.Client.API.room_queue(client_api, room, fn ->
+  def send_state_event(client_api, room_id, event_type, state_key \\ "", event)
+      when is_binary(event_type) and is_binary(state_key) and is_map(event) and is_binary(room_id) do
+    Polyjuice.Client.API.room_queue(client_api, room_id, fn ->
       Polyjuice.Client.API.call(
         client_api,
         %Polyjuice.Client.Endpoint.PutRoomsState{
-          room: room,
+          room: room_id,
           event_type: event_type,
           state_key: state_key,
           content: event
@@ -146,16 +146,16 @@ defmodule Polyjuice.Client.Room do
   """
   @spec update_read_receipt(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           event_id :: String.t(),
           receipt_type :: String.t()
         ) :: :ok | any
-  def update_read_receipt(client_api, room, event_id, receipt_type \\ "m.read")
-      when is_binary(room) and is_binary(event_id) and is_binary(receipt_type) do
+  def update_read_receipt(client_api, room_id, event_id, receipt_type \\ "m.read")
+      when is_binary(room_id) and is_binary(event_id) and is_binary(receipt_type) do
     Polyjuice.Client.API.call(
       client_api,
       %Polyjuice.Client.Endpoint.PostRoomsReceipt{
-        room: room,
+        room: room_id,
         event_id: event_id,
         receipt_type: receipt_type
       }
@@ -167,18 +167,18 @@ defmodule Polyjuice.Client.Room do
   """
   @spec join(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           servers :: list(String.t()),
           third_party_signed :: map | nil
         ) :: {:ok, String.t()} | any
-  def join(client_api, room, servers \\ [], third_party_signed \\ nil)
-      when is_binary(room) and is_list(servers) and
+  def join(client_api, room_id, servers \\ [], third_party_signed \\ nil)
+      when is_binary(room_id) and is_list(servers) and
              (is_map(third_party_signed) or third_party_signed == nil) do
-    Polyjuice.Client.API.room_queue(client_api, room, fn ->
+    Polyjuice.Client.API.room_queue(client_api, room_id, fn ->
       Polyjuice.Client.API.call(
         client_api,
         %Polyjuice.Client.Endpoint.PostJoin{
-          room: room,
+          room: room_id,
           servers: servers,
           third_party_signed: third_party_signed
         }
@@ -191,14 +191,14 @@ defmodule Polyjuice.Client.Room do
   """
   @spec leave(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t()
+          room_id :: String.t()
         ) :: {:ok, String.t()} | any
-  def leave(client_api, room) when is_binary(room) do
-    Polyjuice.Client.API.room_queue(client_api, room, fn ->
+  def leave(client_api, room_id) when is_binary(room_id) do
+    Polyjuice.Client.API.room_queue(client_api, room_id, fn ->
       Polyjuice.Client.API.call(
         client_api,
         %Polyjuice.Client.Endpoint.PostRoomsLeave{
-          room: room
+          room: room_id
         }
       )
     end)
@@ -209,14 +209,14 @@ defmodule Polyjuice.Client.Room do
   """
   @spec forget(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t()
+          room_id :: String.t()
         ) :: {:ok, String.t()} | any
-  def forget(client_api, room) when is_binary(room) do
-    Polyjuice.Client.API.room_queue(client_api, room, fn ->
+  def forget(client_api, room_id) when is_binary(room_id) do
+    Polyjuice.Client.API.room_queue(client_api, room_id, fn ->
       Polyjuice.Client.API.call(
         client_api,
         %Polyjuice.Client.Endpoint.PostRoomsForget{
-          room: room
+          room: room_id
         }
       )
     end)
@@ -227,17 +227,17 @@ defmodule Polyjuice.Client.Room do
   """
   @spec get_messages(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           from :: timeline_pos,
           dir :: :forward | :backward,
           opts :: list()
         ) :: {:ok, map()} | any
-  def get_messages(client_api, room, from, dir, opts \\ [])
-      when is_binary(room) and is_binary(from) and (dir == :forward or dir == :backward) do
+  def get_messages(client_api, room_id, from, dir, opts \\ [])
+      when is_binary(room_id) and is_binary(from) and (dir == :forward or dir == :backward) do
     Polyjuice.Client.API.call(
       client_api,
       %Polyjuice.Client.Endpoint.GetRoomsMessages{
-        room: room,
+        room: room_id,
         from: from,
         dir: dir,
         to: Keyword.get(opts, :to),
@@ -266,13 +266,13 @@ defmodule Polyjuice.Client.Room do
   """
   @spec stream_messages(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           from :: timeline_pos,
           dir :: :forward | :backward,
           opts :: list()
         ) :: Enumerable.t()
-  def stream_messages(client_api, room, from, dir, opts \\ [])
-      when is_binary(room) and is_binary(from) and (dir == :forward or dir == :backward) and
+  def stream_messages(client_api, room_id, from, dir, opts \\ [])
+      when is_binary(room_id) and is_binary(from) and (dir == :forward or dir == :backward) and
              is_list(opts) do
     to = Keyword.get(opts, :to)
     limit = Keyword.get(opts, :limit)
@@ -284,7 +284,7 @@ defmodule Polyjuice.Client.Room do
         case Polyjuice.Client.API.call(
                client_api,
                %Polyjuice.Client.Endpoint.GetRoomsMessages{
-                 room: room,
+                 room: room_id,
                  from: token,
                  dir: dir,
                  to: to,
@@ -321,17 +321,17 @@ defmodule Polyjuice.Client.Room do
   """
   @spec get_state(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           event_type :: String.t(),
           state_key :: String.t()
         ) :: {:ok, String.t()} | any
-  def get_state(client_api, room, event_type \\ nil, state_key \\ "")
+  def get_state(client_api, room_id, event_type \\ nil, state_key \\ "")
       when (is_nil(event_type) or is_binary(event_type)) and is_binary(state_key) and
-             is_binary(room) do
+             is_binary(room_id) do
     Polyjuice.Client.API.call(
       client_api,
       %Polyjuice.Client.Endpoint.GetRoomsState{
-        room: room,
+        room: room_id,
         event_type: event_type,
         state_key: state_key
       }
@@ -356,15 +356,16 @@ defmodule Polyjuice.Client.Room do
   """
   @spec update_read_markers(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           fully_read :: String.t(),
           read :: String.t() | nil
         ) :: {:ok} | any
-  def update_read_markers(client_api, room, fully_read, read \\ nil) do
+  def update_read_markers(client_api, room_id, fully_read, read \\ nil)
+      when is_binary(room_id) and is_binary(fully_read) and (is_binary(read) or read == nil) do
     Polyjuice.Client.API.call(
       client_api,
       %Polyjuice.Client.Endpoint.PostRoomsReadMarkers{
-        room: room,
+        room: room_id,
         fully_read: fully_read,
         read: read
       }
@@ -421,7 +422,7 @@ defmodule Polyjuice.Client.Room do
           client_api :: Polyjuice.Client.API.t(),
           options :: Keyword.t()
         ) :: {:ok, String.t()} | Any
-  def create_room(client_api, options \\ []) do
+  def create_room(client_api, options \\ []) when is_list(options) do
     Polyjuice.Client.API.call(
       client_api,
       struct(%Polyjuice.Client.Endpoint.PostCreateRoom{}, options)
@@ -429,17 +430,17 @@ defmodule Polyjuice.Client.Room do
   end
 
   @doc """
-  This function allow to five a alias to a room
-  it takes:
-  `room`: a string representing the room id
-  `room_alias`: a string representing the new room alias
+  Add an alias to a room.
+
+  Adds the alias `room_alias` to the room with ID `room_id`.
   """
   @spec create_alias(
           client_api :: Polyjuice.Client.API.t(),
-          room :: String.t(),
+          room_id :: String.t(),
           room_alias :: String.t()
         ) :: {:ok, String.t()} | Any
-  def create_alias(client_api, room, room_alias) do
+  def create_alias(client_api, room_id, room_alias)
+      when is_binary(room_id) and is_binary(room_alias) do
     room_alias =
       case String.at(room_alias, 0) do
         "#" -> room_alias
@@ -449,7 +450,7 @@ defmodule Polyjuice.Client.Room do
     Polyjuice.Client.API.call(
       client_api,
       %Polyjuice.Client.Endpoint.PutRoomAlias{
-        room_id: room,
+        room_id: room_id,
         room_alias: room_alias
       }
     )
diff --git a/test/polyjuice/client/endpoint/get_rooms_state_test.exs b/test/polyjuice/client/endpoint/get_rooms_state_test.exs
index 8cdc312..f71415c 100644
--- a/test/polyjuice/client/endpoint/get_rooms_state_test.exs
+++ b/test/polyjuice/client/endpoint/get_rooms_state_test.exs
@@ -1,4 +1,4 @@
-# Copyright 2020 Hubert Chathi <hubert@uhoreg.ca>
+# Copyright 2020 Pierre de Lacroix <pierre@pdelacroix.com>
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.