From f8e9333b4b511bea03943daff5ebe00dd2a15e7d Mon Sep 17 00:00:00 2001 From: Craig Everett Date: Thu, 14 May 2026 11:01:37 +0900 Subject: [PATCH] Doc update --- doc/overview.edoc | 2 +- ebin/hakuzaru.app | 2 +- src/hakuzaru.erl | 2 +- src/hz.erl | 4 ++-- src/hz_aaci.erl | 2 +- src/hz_fetcher.erl | 2 +- src/hz_format.erl | 19 ++++++++++++++++++- src/hz_grids.erl | 36 ++++++++++++++++++++++++++++++++++-- src/hz_key_master.erl | 2 +- src/hz_man.erl | 2 +- src/hz_sophia.erl | 2 +- src/hz_sup.erl | 2 +- zomp.meta | 4 ++-- 13 files changed, 65 insertions(+), 16 deletions(-) diff --git a/doc/overview.edoc b/doc/overview.edoc index b52c71a..61eb6f3 100644 --- a/doc/overview.edoc +++ b/doc/overview.edoc @@ -1,5 +1,5 @@ @author Craig Everett [https://git.qpq.swiss/QPQ-AG/hakuzaru] -@version 0.9.1 +@version 0.9.2 @title Hakuzaru: Gajumaru blockchain bindings for Erlang @doc diff --git a/ebin/hakuzaru.app b/ebin/hakuzaru.app index 4df4bd1..30da878 100644 --- a/ebin/hakuzaru.app +++ b/ebin/hakuzaru.app @@ -3,7 +3,7 @@ {included_applications,[]}, {applications,[stdlib,kernel]}, {description,"Gajumaru interoperation library"}, - {vsn,"0.9.1"}, + {vsn,"0.9.2"}, {modules,[hakuzaru,hz,hz_aaci,hz_fetcher,hz_format,hz_grids, hz_key_master,hz_man,hz_sophia,hz_sup]}, {mod,{hakuzaru,[]}}]}. diff --git a/src/hakuzaru.erl b/src/hakuzaru.erl index a06da60..b0eb0a0 100644 --- a/src/hakuzaru.erl +++ b/src/hakuzaru.erl @@ -6,7 +6,7 @@ %%% @end -module(hakuzaru). --vsn("0.9.1"). +-vsn("0.9.2"). -author("Craig Everett "). -copyright("Craig Everett "). -license("GPL-3.0-or-later"). diff --git a/src/hz.erl b/src/hz.erl index 7a72fac..9aa3999 100644 --- a/src/hz.erl +++ b/src/hz.erl @@ -23,7 +23,7 @@ %%% @end -module(hz). --vsn("0.9.1"). +-vsn("0.9.2"). -author("Craig Everett "). -copyright("Craig Everett "). -license("GPL-3.0-or-later"). @@ -1647,7 +1647,7 @@ convert([], [], _, _, Errors) -> -spec sign_tx(Unsigned, SecKey) -> Result when Unsigned :: string(), SecKey :: binary(), - Result :: {ok, SignedTX} | {error, Reason} + Result :: {ok, SignedTX} | {error, Reason}, SignedTX :: binary(), Reason :: chain_error(). %% @doc diff --git a/src/hz_aaci.erl b/src/hz_aaci.erl index ebf1c6a..7b588e8 100644 --- a/src/hz_aaci.erl +++ b/src/hz_aaci.erl @@ -10,7 +10,7 @@ %%% @end -module(hz_aaci). --vsn("0.9.1"). +-vsn("0.9.2"). -author("Jarvis Carroll "). -copyright("Craig Everett "). -license("GPL-3.0-or-later"). diff --git a/src/hz_fetcher.erl b/src/hz_fetcher.erl index 37f931e..dd2b5c9 100644 --- a/src/hz_fetcher.erl +++ b/src/hz_fetcher.erl @@ -7,7 +7,7 @@ %%% @end -module(hz_fetcher). --vsn("0.9.1"). +-vsn("0.9.2"). -author("Craig Everett "). -copyright("Craig Everett "). -license("MIT"). diff --git a/src/hz_format.erl b/src/hz_format.erl index 2716989..dcd60b8 100644 --- a/src/hz_format.erl +++ b/src/hz_format.erl @@ -21,7 +21,7 @@ %%% @end -module(hz_format). --vsn("0.9.1"). +-vsn("0.9.2"). -author("Craig Everett "). -copyright("Craig Everett "). -license("GPL-3.0-or-later"). @@ -462,9 +462,26 @@ ranks(heresy) -> ["k ", "m ", "b ", "t ", "q ", "e ", "z ", "y ", "r ", "Q "]. +-spec mark(Unit) -> Mark + when Unit :: gaju | puck, + Mark :: $木 | $本. +%% @doc +%% Retrieve the unicode codepoint for the `gaju' mark (木) or the `puck' mark (本). + mark(gaju) -> $木; mark(puck) -> $本. + +-spec one(Unit) -> Pucks + when Unit :: gaju | puck, + Pucks :: 1_000_000_000_000_000_000 | 1. +%% @doc +%% Quickly resolve the number of pucks in a given unit. +%% +%% The number of pucks in a gaju is so large that it can be a little bit annoying +%% to remember the exact amount. This is a helper to simplify this when writing +%% an app against the hakuzaru library when dealing in either unit. + one(gaju) -> 1_000_000_000_000_000_000; one(puck) -> 1. diff --git a/src/hz_grids.erl b/src/hz_grids.erl index a8233b8..1eb9f0a 100644 --- a/src/hz_grids.erl +++ b/src/hz_grids.erl @@ -37,7 +37,7 @@ %%% @end -module(hz_grids). --vsn("0.9.1"). +-vsn("0.9.2"). -export([url/2, url/3, url/4, parse/1, req/2, req/3, req/4]). @@ -47,7 +47,7 @@ Result :: {ok, GRIDS} | uri_string:uri_error(), GRIDS :: uri_string:uri_string(). %% @doc -%% Takes +%% Takes an instruction and an HTTP endpoint location and forms a GRIDS URL. url(Instruction, HTTP) -> case uri_string:parse(HTTP) of @@ -134,6 +134,8 @@ qwargs(Amount, Payload) -> Amount :: non_neg_integer(), Payload :: binary(), URL :: string(). +%% @doc +%% Translate a GRIDS URL into an Erlang terms instruction. parse(GRIDS) -> case uri_string:parse(GRIDS) of @@ -190,13 +192,43 @@ l_to_i(S) -> end. +-spec req(Type, Message) -> Format + when Type :: sign | tx | ack, + Message :: string() | binary(), + Format :: map(). +%% @doc +%% @equiv req(Type, Message, false) + req(Type, Message) -> req(Type, Message, false). + +-spec req(Type, Message, ID) -> Format + when Type :: sign | tx | ack, + Message :: string() | binary(), + ID :: false | string() | binary(), + Format :: map(). +%% @doc +%% Creates a GRIDS message format with the current `NetworkID'. +%% +%% The `ID' parameter indicates which key the requestee should sign with or +%% is `false' to indicate that which key to sign with is up to the requestee. +%% @equiv req(Type, Message, ID, CurrentNetworkID) + req(Type, Message, ID) -> {ok, NetworkID} = hz:network_id(), req(Type, Message, ID, NetworkID). + +-spec req(Type, Message, ID, NetworkID) -> Format + when Type :: sign | tx | ack, + Message :: string() | binary(), + ID :: false | string() | binary(), + NetworkID :: string() | binary(), + Format :: map(). +%% @doc +%% Creates a GRIDS message format. + req(sign, Message, ID, NetworkID) -> #{"grids" => 1, "chain" => "gajumaru", diff --git a/src/hz_key_master.erl b/src/hz_key_master.erl index 5113ee6..85246a5 100644 --- a/src/hz_key_master.erl +++ b/src/hz_key_master.erl @@ -8,7 +8,7 @@ %%% @end -module(hz_key_master). --vsn("0.9.1"). +-vsn("0.9.2"). -export([make_key/1, encode/1, decode/1]). -export([lcg/1]). diff --git a/src/hz_man.erl b/src/hz_man.erl index e38e305..06491ed 100644 --- a/src/hz_man.erl +++ b/src/hz_man.erl @@ -9,7 +9,7 @@ %%% @end -module(hz_man). --vsn("0.9.1"). +-vsn("0.9.2"). -behavior(gen_server). -author("Craig Everett "). -copyright("Craig Everett "). diff --git a/src/hz_sophia.erl b/src/hz_sophia.erl index 76a950d..9254635 100644 --- a/src/hz_sophia.erl +++ b/src/hz_sophia.erl @@ -1,5 +1,5 @@ -module(hz_sophia). --vsn("0.9.1"). +-vsn("0.9.2"). -author("Jarvis Carroll "). -copyright("Jarvis Carroll "). -license("GPL-3.0-or-later"). diff --git a/src/hz_sup.erl b/src/hz_sup.erl index a15e1e9..47ad92b 100644 --- a/src/hz_sup.erl +++ b/src/hz_sup.erl @@ -9,7 +9,7 @@ %%% @end -module(hz_sup). --vsn("0.9.1"). +-vsn("0.9.2"). -behaviour(supervisor). -author("Craig Everett "). -copyright("Craig Everett "). diff --git a/zomp.meta b/zomp.meta index ded02f1..17eed7e 100644 --- a/zomp.meta +++ b/zomp.meta @@ -1,10 +1,10 @@ {name,"Hakuzaru"}. {type,app}. {modules,[]}. -{author,"Craig Everett"}. {prefix,"hz"}. +{author,"Craig Everett"}. {desc,"Gajumaru interoperation library"}. -{package_id,{"otpr","hakuzaru",{0,9,1}}}. +{package_id,{"otpr","hakuzaru",{0,9,2}}}. {deps,[{"otpr","sophia",{9,0,0}}, {"otpr","gmserialization",{0,1,3}}, {"otpr","gmbytecode",{3,4,1}},