📝 Writing project documentation

lib/elven_gard/packet.ex

@@ -64,9 +64,9 @@ defmodule ElvenGard.Packet do
   end
 
   @doc """
-  Define an useless packet
+  Define an unused packet
 
-  ¯\\_(ツ)_/¯
+  ¯\\\\_(ツ)_/¯
   """
   defmacro useless_packet(packet_name) do
     caller = __CALLER__.module

lib/elven_gard/protocol.ex

@@ -4,6 +4,9 @@ defmodule ElvenGard.Protocol do
   pattern match by a PacketHandler.
 
   /!\\ No side effect: Cannot change or modify the current `ElvenGard.Structures.Client`
+
+  TODO: I don't really know if it's usefull to add `pre` and `post` hooks for `encode` and
+  `decode`. I'll probably remove them later.
   """
 
   alias ElvenGard.Structures.Client
@@ -15,17 +18,20 @@ defmodule ElvenGard.Protocol do
 
   @doc """
   Prepare the packet to be sent for the encode function
+
+  NOTE: This function is called by `ElvenGard.Structures.Client.send/2`
   """
   @callback pre_encode(data :: term, client :: Client.t()) :: term
 
   @doc """
-  Encodes a packet so that it can be sent to a client.
+  Transforms a term into a packet that can be sent to the client
+
   You can, for example, apply your cryptographic algorithm.
   """
   @callback encode(data :: term) :: term
 
   @doc """
-  If not already done by the `encode` function, this function will transform his
+  If not already done by the `c:encode/1` function, this function will transform his
   result into a binary.
   """
   @callback post_encode(data :: term, client :: Client.t()) :: binary
@@ -37,14 +43,18 @@ defmodule ElvenGard.Protocol do
 
   @doc """
   Transform a raw packet to an understandable packet.
+
   You can, for example, apply your cryptographic algorithm and split your packet.
   """
   @callback decode(data :: term) :: term
 
   @doc """
-  If not already done by the `decode` function, this function will transform his
+  If not already done by the `c:decode/1` function, this function will transform his
   result into a tuple.
-  This function must return a tuple starting with your packet header followed by params.
+
+  NOTE: This function must return a tuple starting with your packet header followed by
+  params or a list of tuple.  
+  The result of this function will then be used by `c:ElvenGard.Packet.handle_packet/3`
   """
   @callback post_decode(data :: term, client :: Client.t()) :: {term, map} | list(tuple)
 
@@ -73,7 +83,8 @@ defmodule ElvenGard.Protocol do
 
       @doc """
       Successively applies functions `pre_decode`, `decode` and `post_decode`
-      Can return a packet list
+
+      NOTE: Can return a packet list
       """
       @spec complete_decode(binary, Client.t()) :: tuple | list(tuple)
       def complete_decode(data, %Client{} = client) do
@@ -107,6 +118,7 @@ defmodule ElvenGard.Protocol do
                      post_encode: 2,
                      pre_decode: 2,
                      post_decode: 2,
+                     complete_encode: 2,
                      complete_decode: 2
     end
   end

lib/elven_gard/type.ex

@@ -3,10 +3,21 @@ defmodule ElvenGard.Type do
   Define a behaviour for custom type (packet parsing)
   """
 
+  @typedoc "Represents a part of a raw packet received by the client"
   @type encoded_term :: bitstring
+  @typedoc "Represents the term that this class provides"
   @type decoded_term :: term
 
+  @doc """
+  Transforms a term into a packet that can be sent to the client
+  """
   @callback encode(decoded_term, opts :: list) :: term
+
+  @doc """
+  Transforms a packet received by a client into a term that can be used by a protocol
+
+  NOTE: The result of this function will then be used by `c:ElvenGard.Protocol.decode/1`
+  """
   @callback decode(encoded_term, opts :: list) :: term
 
   @doc false
@@ -17,12 +28,12 @@ defmodule ElvenGard.Type do
       @behaviour unquote(parent)
 
       @doc """
-      Encode a bitstring without params
+      Encode a term without passing any options
       """
       def encode(val), do: encode(val, [])
 
       @doc """
-      Decode a term without params
+      Decode a bitstring without passing any options
       """
       def decode(val), do: decode(val, [])
     end

lib/elven_gard/view.ex

@@ -5,6 +5,9 @@ defmodule ElvenGard.View do
 
   alias ElvenGard.UnknownViewError
 
+  @doc """
+  Build a packet to send to the client
+  """
   @callback render(type :: atom, opts :: map) :: term
 
   @anno if :erlang.system_info(:otp_release) >= '19', do: [generated: true], else: [line: -1]