Some more inline docs

suvash · Apr 14, 2015 · db76295 · db76295
1 parent dc914de
commit db76295
Show file tree

Hide file tree

Showing 4 changed files with 155 additions and 8 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
+/doc
 /cover
 /_build
 /deps

diff --git a/lib/hulaaki/decoder.ex b/lib/hulaaki/decoder.ex
@@ -1,7 +1,14 @@
 defmodule Hulaaki.Decoder do
   alias Hulaaki.Message
   use Bitwise
-
+  @moduledoc """
+  Provides functions for decoding bytes(binary) to Message structs and
+  decode remaining length as specified in MQTT 3.1.1 spec section 2.2.3
+  """
+
+  @doc """
+  Decodes a binary to a tuple containing Message struct and a remainder
+  """
   def decode(<<first_byte::bits-8, _rest::bits>> = bytes) do
     case first_byte do
       << 1::size(4), _::size(4)>> -> decode_connect(bytes)
@@ -24,6 +31,10 @@ defmodule Hulaaki.Decoder do
     end
   end
 
+  @doc """
+  Decodes remaining length from bytes encoded using a variable length
+  encoding scheme specified in MQTT 3.1.1 spec section 2.2.3
+  """
   def decode_remaining_length(<<0>>), do: {0, ""}
 
   def decode_remaining_length(bytes) do

diff --git a/lib/hulaaki/encoder.ex b/lib/hulaaki/encoder.ex
@@ -1,12 +1,18 @@
 defmodule Hulaaki.Encoder do
   alias Hulaaki.Message
   require Bitwise
+  @moduledoc """
+  Provides functions for encoding Message structs to bytes(binary)
+  """
 
   @type dup :: 0|1
   @type qos :: 0|1|2
   @type retain :: 0|1
   @type packet_value :: 1|2|3|4|5|6|7|8|9|10|11|12|13|14
 
+  @doc """
+  Encodes the fixed header (as specified in MQTT spec) for a given Message struct
+  """
   def encode_fixed_header(%Message.Connect{} = message) do
     remaining_length = calculate_remaining_length(message)
     encode_fixed_header_first_byte(1, 0, 0, 0) <>
@@ -83,6 +89,9 @@ defmodule Hulaaki.Encoder do
       encode_fixed_header_second_byte(0)
   end
 
+  @doc """
+  Calculates the remaining length (as specified in MQTT spec) for a given Message struct
+  """
   def calculate_remaining_length(%Message.Connect{client_id: client_id,
                                                   username: username,
                                                   password: password,
@@ -163,6 +172,10 @@ defmodule Hulaaki.Encoder do
       encode_fixed_header_remaining_length(remaining_length)
   end
 
+  @doc """
+  Encodes remaining length using a variable length
+  encoding scheme specified in MQTT 3.1.1 spec section 2.2.3
+  """
   @spec encode_fixed_header_remaining_length(number) :: binary
   def encode_fixed_header_remaining_length(0), do: <<0>>
 
@@ -186,6 +199,9 @@ defmodule Hulaaki.Encoder do
     end
   end
 
+  @doc """
+  Encodes variable header for a given Message struct
+  """
   def encode_variable_header(%Message.Connect{username: username,
                                               password: password,
                                               will_qos: will_qos,
@@ -266,6 +282,9 @@ defmodule Hulaaki.Encoder do
     <<id::size(16)>>
   end
 
+  @doc """
+  Encodes the payload for a given Message struct
+  """
   def encode_payload(%Message.Connect{client_id: id,
                                       username: username,
                                       password: password,

diff --git a/lib/hulaaki/message.ex b/lib/hulaaki/message.ex
@@ -4,11 +4,25 @@ defmodule Hulaaki.Message do
   packets in the MQTT protocol.
   """
 
-  # TODO: number of topics and number of qoses must be equal
-
   defmodule Connect do
+    @moduledoc """
+    Struct for Hulaaki Connect
+
+    ## Fields
+
+      * `client_id`     : A string(binary) representing the client.
+      * `username`      : A string(binary) representing the username.
+      * `password`      : A string(binary) representing the password.
+      * `will_topic`    : A string(binary) representing the will topic.
+      * `will_message`  : A string(binary) representing the will message.
+      * `will_qos`      : An integer of value either 0,1,2 representing the will qos.
+      * `will_retain`   : An integer of value either 0,1 representing the will retain.
+      * `clean_session` : An integer of value either 0,1 representing whether the session is clean.
+      * `keep_alive`    : An integer representing the keep alive value in seconds.
+    """
+
     @type t :: %__MODULE__{
-              client_id: non_neg_integer,
+              client_id: String.t,
               username: String.t,
               password: String.t,
               will_topic: String.t,
@@ -31,7 +45,7 @@ defmodule Hulaaki.Message do
   end
 
   @doc """
-  Creates a Connect struct with the guards applied.
+  Creates a Connect struct with the guards applied to the arguments.
   """
   def connect(client_id, username, password,
               will_topic, will_message, will_qos,
@@ -54,6 +68,15 @@ defmodule Hulaaki.Message do
   end
 
   defmodule ConnAck do
+    @moduledoc """
+    Struct for Hulaaki ConnAck
+
+    ## Fields
+
+      * `session_present` : An integer of value either 0,1 representing the session present.
+      * `return_code`     : An integer of value either 0,1,2,3,4,5 representing the return code.
+    """
+
     @type t :: %__MODULE__{session_present: 0|1, return_code: 1|2|3|4|5, type: atom}
     defstruct [:session_present, :return_code, type: :CONNACK]
   end
@@ -71,6 +94,18 @@ defmodule Hulaaki.Message do
   end
 
   defmodule Publish do
+    @moduledoc """
+    Struct for Hulaaki Publish
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+      * `topic`     : A string(binary) representing the topic.
+      * `message`   : A string(binary) representing the message.
+      * `dup`       : An integer of value either 0,1 representing the dup bit.
+      * `qos`       : An integer of value either 0,1,2 representing the qos bit.
+      * `retain`    : An integer of value either 0,1 representing the retain bit.
+    """
+
     @type t :: %__MODULE__{
                id: non_neg_integer,
                topic: String.t,
@@ -88,6 +123,7 @@ defmodule Hulaaki.Message do
   def publish(packet_id, topic, message, dup, qos, retain)
     when is_integer(packet_id)
     and packet_id > 0
+    and packet_id <= 65_536
     and is_binary(topic)
     and is_binary(message)
     and (dup == 0 or dup == 1)
@@ -99,6 +135,13 @@ defmodule Hulaaki.Message do
   end
 
   defmodule PubAck do
+    @moduledoc """
+    Struct for Hulaaki PubAck
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+    """
+
     @type t :: %__MODULE__{id: non_neg_integer, type: atom}
     defstruct [:id, type: :PUBACK]
   end
@@ -108,12 +151,20 @@ defmodule Hulaaki.Message do
   """
   def publish_ack(packet_id)
     when is_integer(packet_id)
-    and packet_id > 0 do
+    and packet_id > 0
+    and packet_id <= 65_536 do
 
       %PubAck{id: packet_id}
   end
 
   defmodule PubRec do
+    @moduledoc """
+    Struct for Hulaaki PubRec
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+    """
+
     @type t :: %__MODULE__{id: non_neg_integer, type: atom}
     defstruct [:id, type: :PUBREC]
   end
@@ -129,6 +180,13 @@ defmodule Hulaaki.Message do
   end
 
   defmodule PubRel do
+    @moduledoc """
+    Struct for Hulaaki PubRel
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+    """
+
     @type t :: %__MODULE__{id: non_neg_integer, type: atom}
     defstruct [:id, type: :PUBREL]
   end
@@ -138,12 +196,20 @@ defmodule Hulaaki.Message do
   """
   def publish_release(packet_id)
     when is_integer(packet_id)
-    and packet_id > 0 do
+    and packet_id > 0
+    and packet_id <= 65_536 do
 
       %PubRel{id: packet_id}
   end
 
   defmodule PubComp do
+    @moduledoc """
+    Struct for Hulaaki PubComp
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+    """
+
     @type t :: %__MODULE__{id: non_neg_integer, type: atom}
     defstruct [:id, type: :PUBCOMP]
   end
@@ -153,11 +219,22 @@ defmodule Hulaaki.Message do
   """
   def publish_complete(packet_id)
     when is_integer(packet_id)
-    and packet_id > 0 do
+    and packet_id > 0
+    and packet_id <= 65_536 do
 
       %PubComp{id: packet_id}
   end
+
   defmodule Subscribe do
+    @moduledoc """
+    Struct for Hulaaki Subscribe
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+      * `topics`          : A list of string(binary) representing various topics.
+      * `requested_qoses` : A list of integer of value 0,1,2 representing qoses.
+    """
+
     @type t :: %__MODULE__{
                id: non_neg_integer,
                topics: list(String.t),
@@ -172,9 +249,11 @@ defmodule Hulaaki.Message do
   def subscribe(packet_id, topics, requested_qoses)
     when is_integer(packet_id)
     and packet_id > 0
+    and packet_id <= 65_536
     and is_list(topics)
     and is_list(requested_qoses)
     and length(requested_qoses) == length(topics) do
+
       clean_topics = Enum.filter(topics, fn(x) -> is_binary(x) end)
       valid_qos? = fn(x) -> (x == 0 or x == 1 or x == 2) end
       clean_qoses = Enum.filter(requested_qoses, valid_qos?)
@@ -183,6 +262,14 @@ defmodule Hulaaki.Message do
   end
 
   defmodule SubAck do
+    @moduledoc """
+    Struct for Hulaaki SubAck
+
+    ## Fields
+      * `packet_id`     : An integer of value upto 65536 (2 bytes) representing packet identifier
+      * `granted_qoses` : A list of integer of value 0,1,2,128 representing qoses.
+    """
+
     @type t :: %__MODULE__{
                id: non_neg_integer,
                granted_qoses: list(0|1|2|128),
@@ -196,14 +283,24 @@ defmodule Hulaaki.Message do
   def subscribe_ack(packet_id, granted_qoses)
     when is_integer(packet_id)
     and packet_id > 0
+    and packet_id <= 65_536
     and is_list(granted_qoses) do
+
       valid_qos? = fn(x) -> (x == 0 or x == 1 or x == 2 or x == 128) end
       clean_qoses = Enum.filter(granted_qoses, valid_qos?)
 
       %SubAck{id: packet_id, granted_qoses: clean_qoses}
   end
 
   defmodule Unsubscribe do
+    @moduledoc """
+    Struct for Hulaaki Unsubscribe
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+      * `topics`    : A list of string(binary) representing various topics.
+    """
+
     @type t :: %__MODULE__{id: non_neg_integer, topics: list(String.t), type: atom}
     defstruct [:id, :topics, type: :UNSUBSCRIBE]
   end
@@ -221,6 +318,13 @@ defmodule Hulaaki.Message do
   end
 
   defmodule UnsubAck do
+    @moduledoc """
+    Struct for Hulaaki UnsubAck
+
+    ## Fields
+      * `packet_id` : An integer of value upto 65536 (2 bytes) representing packet identifier
+    """
+
     @type t :: %__MODULE__{id: non_neg_integer, type: atom}
     defstruct [:id, type: :UNSUBACK]
   end
@@ -236,6 +340,10 @@ defmodule Hulaaki.Message do
   end
 
   defmodule PingReq do
+    @moduledoc """
+    Struct for Hulaaki PingReq
+    """
+
     @type t :: %__MODULE__{type: atom}
     defstruct type: :PINGREQ
   end
@@ -248,6 +356,10 @@ defmodule Hulaaki.Message do
   end
 
   defmodule PingResp do
+    @moduledoc """
+    Struct for Hulaaki PingResp
+    """
+
     @type t :: %__MODULE__{type: atom}
     defstruct type: :PINGRESP
   end
@@ -260,6 +372,10 @@ defmodule Hulaaki.Message do
   end
 
   defmodule Disconnect do
+    @moduledoc """
+    Struct for Hulaaki Disconnect
+    """
+
     @type t :: %__MODULE__{type: atom}
     defstruct type: :DISCONNECT
   end
-Original file line number
+Diff line change
@@ -1,3 +1,4 @@
+    /doc
     /cover
     /_build
     /deps
@@ Expand Down @@