From 23c13f607e44089caad8c0350ee963a511cc1f3c Mon Sep 17 00:00:00 2001
From: Jarvis Carroll <jarviscarroll@qpq.swiss>
Date: Fri, 15 May 2026 06:15:15 +0000
Subject: [PATCH] Document hz_aaci functions

Once the types were documented, the functions were easy to document. Just say "see erlang_expr/0 for details" over and over! ;p
---
 src/hz_aaci.erl | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/src/hz_aaci.erl b/src/hz_aaci.erl
index a18f142..47d659d 100644
--- a/src/hz_aaci.erl
+++ b/src/hz_aaci.erl
@@ -375,8 +375,10 @@
          AACI   :: aaci(),
          Reason :: term().
 %% @doc
-%% Compile a contract and extract the function spec meta for use in future formation
-%% of calldata
+%% Compile a contract and extract the contract type information for forming contract calls
+%% This is the simplest (but slowest) way of getting access to the AACI
+%% structure for a contract. Having the AACI is not strictly necessary, but
+%% makes it much more convenient to form contract calls and view their results.
 
 prepare_from_file(Path) ->
     case so_compiler:file(Path, [{aci, json}]) of
@@ -388,6 +390,10 @@ prepare_from_file(Path) ->
     when ACI  :: term(),
          AACI :: aaci().
 
+%% @doc
+%% Convert the ACI structure produced by the compiler into the AACI format used by Hakuzaru
+%% See the documentation for the aaci/0 type for more information.
+
 prepare(ACI) ->
     % We want to take the types represented by the ACI, things like N1.T(N2.T),
     % and dereference them down to concrete types like
@@ -1209,6 +1215,14 @@ coerce_direction(Type, Term, from_fate) ->
          Reason   :: term(),
          PathStep :: term().
 
+%% @doc
+%% Convert a FATE-flavored Erlang term into a Sophia-flavored Erlang term
+%% Typically this is called by hakuzaru for you when decoding results from the
+%% chain, if you ask for the 'erlang' format, but you can call this function
+%% manually if you have a result in the 'fate' format, and need the 'erlang'
+%% format now. See the documentation of the erlang_repr/0 type for more
+%% information.
+
 fate_to_erlang({_, _, integer}, S) when is_integer(S) ->
     {ok, S};
 fate_to_erlang({_, _, address}, {address, Bin}) ->
@@ -1298,9 +1312,12 @@ opaque_type_to_iolist(N, _) ->
          Reason :: bad_fun_name.
 
 %% @doc
-%% Look up the type information of a given function, in the AACI provided by
-%% prepare_contract/1. This type information, particularly the return type, is
-%% useful for calling decode_bytearray/2.
+%% Extract the type information for a particular function from the AACI
+%% If you want to manually convert a FATE result into the Sophia-flavored
+%% Erlang representation, or manually convert some or all of the inputs for a
+%% contract call yourself, this function gives you all of the annotated types
+%% associated with a contract entrypoint. For more information, see the
+%% documentation for the annotated_type/0 type.
 
 get_function_signature({aaci, _, FunDefs, _}, Fun) ->
     case maps:find(Fun, FunDefs) of