More documentation and some cleanup

src/enoise.erl

@@ -28,12 +28,18 @@
 -type noise_keypair() :: enoise_keypair:keypair().
 
 -type noise_options() :: [noise_option()].
+%% A list of Noise options is a proplist, it *must* contain a value `noise'
+%% that describes which Noise configuration to use. It is possible to give a
+%% `prologue' to the protocol. And for the protocol to work, the correct
+%% configuration of pre-defined keys (`s', `e', `rs', `re') should also be
+%% provided.
+
 -type noise_option() :: {noise, noise_protocol_option()} %% Required
-                      | {e, noise_keypair()} %% Optional
+                      | {e, noise_keypair()} %% Mandatary depending on `noise'
                       | {s, noise_keypair()}
                       | {re, noise_key()}
                       | {rs, noise_key()}
-                      | {prologue, binary()}.
+                      | {prologue, binary()}. %% Optional
 
 -type noise_protocol_option() :: enoise_protocol:protocol() | string() |
 binary().
@@ -52,6 +58,8 @@ binary().
 
 %% @doc Upgrades a gen_tcp, or equivalent, connected socket to a Noise socket,
 %% that is, performs the client-side noise handshake.
+%%
+%% {@link noise_options()} is a proplist.
 %% @end
 -spec connect(TcpSock :: gen_tcp:socket(),
               Options :: noise_options()) ->
@@ -61,6 +69,8 @@ connect(TcpSock, Options) ->
 
 %% @doc Upgrades a gen_tcp, or equivalent, connected socket to a Noise socket,
 %% that is, performs the server-side noise handshake.
+%%
+%% {@link noise_options()} is a proplist.
 %% @end
 -spec accept(TcpSock :: gen_tcp:socket(),
              Options :: noise_options()) ->
@@ -74,6 +84,12 @@ accept(TcpSock, Options) ->
 send(#enoise{ pid = Pid }, Data) ->
     enoise_connection:send(Pid, Data).
 
+%% @equiv recv(Socket, Length, infinity)
+-spec recv(Socket :: noise_socket(), Length :: integer()) ->
+        {ok, binary()} | {error, term()}.
+recv(Socket, Length) ->
+    recv(Socket, Length, infinity).
+
 %% @doc Receives a packet from a socket in passive mode. A closed socket is
 %% indicated by return value `{error, closed}'.
 %%
@@ -85,11 +101,6 @@ send(#enoise{ pid = Pid }, Data) ->
 %% Optional argument `Timeout' specifies a time-out in milliseconds. The
 %% default value is `infinity'.
 %% @end
--spec recv(Socket :: noise_socket(), Length :: integer()) ->
-        {ok, binary()} | {error, term()}.
-recv(Socket, Length) ->
-    recv(Socket, Length, infinity).
-
 -spec recv(Socket :: noise_socket(), Length :: integer(),
            Timeout :: integer() | infinity) ->
         {ok, binary()} | {error, term()}.

src/enoise_cipher_state.erl

@@ -1,6 +1,10 @@
-%%%-------------------------------------------------------------------
+%%% ------------------------------------------------------------------
-%%% @copyright (C) 2018, Aeternity Anstalt
+%%% @copyright 2018, Aeternity Anstalt
-%%%-------------------------------------------------------------------
+%%%
+%%% @doc Module encapsulating a Noise Cipher state
+%%%
+%%% @end
+%%% ------------------------------------------------------------------
 
 -module(enoise_cipher_state).
 

src/enoise_connection.erl

@@ -1,6 +1,11 @@
-%%%-------------------------------------------------------------------
+%%% ------------------------------------------------------------------
-%%% @copyright (C) 2018, Aeternity Anstalt
+%%% @copyright 2018, Aeternity Anstalt
-%%%-------------------------------------------------------------------
+%%%
+%%% @doc Module implementing a gen_server for holding a handshaked
+%%% Noise connection.
+%%%
+%%% @end
+%%% ------------------------------------------------------------------
 
 -module(enoise_connection).
 
@@ -16,6 +21,7 @@
          terminate/2, code_change/3]).
 
 -record(enoise, { pid }).
+
 -record(state, {rx, tx, owner, tcp_sock, active, buf = <<>>, rawbuf = <<>>}).
 
 %% -- API --------------------------------------------------------------------

src/enoise_crypto.erl

@@ -1,6 +1,10 @@
-%%%-------------------------------------------------------------------
+%%% ------------------------------------------------------------------
-%%% @copyright (C) 2018, Aeternity Anstalt
+%%% @copyright 2018, Aeternity Anstalt
-%%%-------------------------------------------------------------------
+%%%
+%%% @doc Module implementing crypto primitives needed by Noise protocol
+%%%
+%%% @end
+%%% ------------------------------------------------------------------
 
 -module(enoise_crypto).
 

src/enoise_hs_state.erl

@@ -1,6 +1,10 @@
-%%%-------------------------------------------------------------------
+%%% ------------------------------------------------------------------
-%%% @copyright (C) 2018, Aeternity Anstalt
+%%% @copyright 2018, Aeternity Anstalt
-%%%-------------------------------------------------------------------
+%%%
+%%% @doc Module encapsulating a Noise handshake state
+%%%
+%%% @end
+%%% ------------------------------------------------------------------
 
 -module(enoise_hs_state).
 

src/enoise_keypair.erl

@@ -59,6 +59,7 @@ pubkey(#kp{ pub = P }) ->
     P.
 
 %% @doc Accessor function - return the secret key of the key pair.
+%% This function will throw an error if the key pair is "public only".
 -spec seckey(KeyPair :: keypair()) -> binary().
 seckey(#kp{ sec = undefined }) ->
     error(keypair_is_public_only);

src/enoise_opts.erl

@@ -1,10 +0,0 @@
-%%%-------------------------------------------------------------------
-%%% @copyright (C) 2018, Aeternity Anstalt
-%%%-------------------------------------------------------------------
-
--module(enoise_opts).
-
--export([tcp_opts/1]).
-
-tcp_opts(_Options) ->
-    [{active, true}, binary, {reuseaddr, true}].

src/enoise_protocol.erl

@@ -1,6 +1,10 @@
-%%%-------------------------------------------------------------------
+%%% ------------------------------------------------------------------
-%%% @copyright (C) 2018, Aeternity Anstalt
+%%% @copyright 2018, Aeternity Anstalt
-%%%-------------------------------------------------------------------
+%%%
+%%% @doc Module defining Noise protocol configurations
+%%%
+%%% @end
+%%% ------------------------------------------------------------------
 
 -module(enoise_protocol).
 

src/enoise_sym_state.erl

@@ -1,6 +1,10 @@
-%%%-------------------------------------------------------------------
+%%% ------------------------------------------------------------------
-%%% @copyright (C) 2018, Aeternity Anstalt
+%%% @copyright 2018, Aeternity Anstalt
-%%%-------------------------------------------------------------------
+%%%
+%%% @doc Module encapsulating a Noise symmetric (hash) state
+%%%
+%%% @end
+%%% ------------------------------------------------------------------
 
 -module(enoise_sym_state).