diff --git a/src/pgo.erl b/src/pgo.erl
index d08a259..3c263eb 100644
--- a/src/pgo.erl
+++ b/src/pgo.erl
@@ -1,13 +1,10 @@
-%%% ---------------------------------------------------------------------------
-%%% @author Tristan Sloughter <t@crashfast.com>
-%%%
-%%% @doc Postgres driver and pool for Erlang.
-%%%
-%%% This module provides functions for interacting with a pool and
-%%  querying the database.
-%%% @end
-%%% ---------------------------------------------------------------------------
 -module(pgo).
+-author("Tristan Sloughter <tristan@sloughter.dev>").
+-moduledoc """
+Postgres driver and pool for Erlang.
+This module provides functions for interacting with a pool and
+ querying the database.
+""".
 
 -export([start_pool/2,
          query/1,
@@ -88,7 +85,7 @@ start_pool(Name, PoolConfig) ->
 query(Query) ->
     query(Query, [], #{}).
 
-%% @equiv query(Query, Params, #{})
+-doc #{equiv => query(Query, Params, #{})}.
 -spec query(iodata(), list()) -> result().
 query(Query, Params) ->
     query(Query, Params, #{}).
@@ -211,7 +208,9 @@ with_conn(Conn, Fun) ->
             end
     end.
 
-%% @doc Returns a connection from the pool.
+-doc """
+Returns a connection from the pool.
+""".
 -spec checkout(atom()) -> {ok, pgo_pool:pool_ref(), pgo_pool:conn()} | {error, any()}.
 checkout(Pool) ->
     pgo_pool:checkout(Pool, []).
diff --git a/src/pgo_app.erl b/src/pgo_app.erl
index 4c3922a..dd277d8 100644
--- a/src/pgo_app.erl
+++ b/src/pgo_app.erl
@@ -1,8 +1,7 @@
-%%%-------------------------------------------------------------------
-%% @doc pgo application
-%% @end
-%%%-------------------------------------------------------------------
 -module(pgo_app).
+-moduledoc """
+pgo application
+""".
 
 -behaviour(application).
 
diff --git a/src/pgo_connection.erl b/src/pgo_connection.erl
index d5fe2ae..247d0b8 100644
--- a/src/pgo_connection.erl
+++ b/src/pgo_connection.erl
@@ -176,7 +176,7 @@ handle_event(info, {'EXIT', _, _Reason}, _Data) ->
 handle_event(info, {ssl_closed, _}, _Data) ->
     keep_state_and_data.
 
-%% @private
+-doc hidden.
 terminate(_Reason, _, #data{conn=undefined}) ->
     ok;
 terminate(_Reason, _, #data{conn=Conn}) ->
diff --git a/src/pgo_handler.erl b/src/pgo_handler.erl
index 7190ed5..e9bd07b 100644
--- a/src/pgo_handler.erl
+++ b/src/pgo_handler.erl
@@ -85,9 +85,9 @@ close(#conn{socket=Socket}) ->
     unlink(Socket),
     exit(Socket, shutdown).
 
-%%--------------------------------------------------------------------
-%% @doc Actually open (or re-open) the connection.
-%%
+-doc """
+Actually open (or re-open) the connection.
+""".
 -spec open(atom(), pgo:pool_config()) -> {ok, pgo_pool:conn()} | {error, any()}.
 open(Pool, PoolConfig) ->
     Host = maps:get(host, PoolConfig, ?DEFAULT_HOST),
@@ -128,9 +128,9 @@ open(Pool, PoolConfig) ->
             ConnectError
     end.
 
-%%--------------------------------------------------------------------
-%% @doc Setup the connection, handling the authentication handshake.
-%%
+-doc """
+Setup the connection, handling the authentication handshake.
+""".
 setup(Conn, Options) ->
     case maps:get(ssl, Options, undefined) of
         false ->
diff --git a/src/pgo_protocol.erl b/src/pgo_protocol.erl
index 5ba3369..425f733 100644
--- a/src/pgo_protocol.erl
+++ b/src/pgo_protocol.erl
@@ -189,9 +189,9 @@ encode_execute_message(PortalName, MaxRows) ->
     MessageLen = iolist_size(PortalName) + 9,
     [<<$E, MessageLen:32/integer>>, PortalName, <<0, MaxRows:32/integer>>].
 
-%%--------------------------------------------------------------------
-%% @doc Encode a sync message.
-%%
+-doc """
+Encode a sync message.
+""".
 -spec encode_sync_message() -> binary().
 encode_sync_message() ->
     <<$S, 4:32/integer>>.
@@ -570,9 +570,9 @@ decode_strings(Binary) ->
     <<Strings:Size/binary, 0>> = Binary,
     binary:split(Strings, <<0>>, [global]).
 
-%%--------------------------------------------------------------------
-%% @doc Decode a row format.
-%%
+-doc """
+Decode a row format.
+""".
 -spec decode_row([#row_description_field{}], [binary()], atom(), proplists:proplist()) -> tuple().
 decode_row(Descs, Values, OIDMap, DecodeOptions) ->
     case proplists:get_bool(return_rows_as_maps, DecodeOptions) of
diff --git a/src/pgo_sasl_prep_profile.erl b/src/pgo_sasl_prep_profile.erl
index 312cd4a..3d0f5d0 100644
--- a/src/pgo_sasl_prep_profile.erl
+++ b/src/pgo_sasl_prep_profile.erl
@@ -68,8 +68,10 @@ is_non_ascii_control_character(C) ->
         orelse (16#FFF9 =< C andalso C =< 16#FFFC)
         orelse (16#1D173 =< C andalso C =< 16#1D17A).
 
-%% @doc Return true if the given character is a private use character
-%% as defined by https://tools.ietf.org/html/rfc3454#appendix-C.3
+-doc """
+Return true if the given character is a private use character
+as defined by https://tools.ietf.org/html/rfc3454#appendix-C.3
+""".
 -spec is_private_use_characters(char()) -> boolean().
 is_private_use_characters(C) ->
     (16#E000 =< C andalso C =< 16#F8FF)
@@ -141,8 +143,10 @@ is_change_display_properties_or_deprecated_char(C) ->
         orelse C == 16#206E
         orelse C == 16#206F.
 
-%% @doc Return true if the given character is a tagging character as defined by
-%% https://tools.ietf.org/html/rfc3454#appendix-C.9
+-doc """
+Return true if the given character is a tagging character as defined by
+https://tools.ietf.org/html/rfc3454#appendix-C.9
+""".
 -spec is_tagging_char(char()) -> boolean().
 is_tagging_char(C) ->
     C == 16#E0001 orelse
diff --git a/src/pgo_scram.erl b/src/pgo_scram.erl
index 86d64bc..3ebedbc 100644
--- a/src/pgo_scram.erl
+++ b/src/pgo_scram.erl
@@ -1,18 +1,18 @@
 %%% Module from epgsql https://github.com/epgsql/epgsql
 
 %%% coding: utf-8
-%%% @doc
-%%% SCRAM--SHA-256 helper functions
-%%%
-%%% <ul>
-%%%  <li>[https://www.postgresql.org/docs/current/static/sasl-authentication.html]</li>
-%%%  <li>[https://en.wikipedia.org/wiki/Salted_Challenge_Response_Authentication_Mechanism]</li>
-%%%  <li>[https://tools.ietf.org/html/rfc7677]</li>
-%%%  <li>[https://tools.ietf.org/html/rfc5802]</li>
-%%% </ul>
-%%% @end
 
 -module(pgo_scram).
+-moduledoc """
+SCRAM--SHA-256 helper functions
+
+<ul>
+ <li>[https://www.postgresql.org/docs/current/static/sasl-authentication.html]</li>
+ <li>[https://en.wikipedia.org/wiki/Salted_Challenge_Response_Authentication_Mechanism]</li>
+ <li>[https://tools.ietf.org/html/rfc7677]</li>
+ <li>[https://tools.ietf.org/html/rfc5802]</li>
+</ul>
+""".
 -export([get_nonce/1,
          get_client_first/2,
          get_client_final/4,
@@ -39,9 +39,11 @@ get_client_first(UserName, Nonce) ->
 client_first_bare(UserName, Nonce) ->
     [<<"n=">>, UserName, <<",r=">>, Nonce].
 
-%% @doc Generate unique ASCII string.
-%% Resulting string length isn't guaranteed, but it's guaranteed to be unique and will
-%% contain `NumRandomBytes' of random data.
+-doc """
+Generate unique ASCII string.
+Resulting string length isn't guaranteed, but it's guaranteed to be unique and will
+contain `NumRandomBytes` of random data.
+""".
 -spec get_nonce(pos_integer()) -> nonce().
 get_nonce(NumRandomBytes) when NumRandomBytes < 255 ->
     Random = crypto:strong_rand_bytes(NumRandomBytes),