cleanup docs for multiclause functions and add examples

lib/ssb_bfe.ex

@@ -3,6 +3,19 @@ defmodule SsbBfe do
   Binary Field Encodings (BFE) for Secure Scuttlebutt (SSB).
 
   Encode and decode TFD values.
+
+  ## Examples
+
+    iex> SsbBfe.encode("@HEqy940T6uB+T+d9Jaa58aNfRzLx9eRWqkZljBmnkmk=.ed25519")
+    <<0, 0, 28, 74, 178, 247, 141, 19, 234, 224, 126, 79, 231, 125, 37, 166, 185,
+      241, 163, 95, 71, 50, 241, 245, 228, 86, 170, 70, 101, 140, 25, 167, 146,
+    105>>
+
+    ...> SsbBfe.decode(<<0, 0, 28, 74, 178, 247, 141, 19, 234, 224, 126, 79, 231, 125, 37, 166, 185,
+      241, 163, 95, 71, 50, 241, 245, 228, 86, 170, 70, 101, 140, 25, 167, 146,
+    105>>)
+    "@HEqy940T6uB+T+d9Jaa58aNfRzLx9eRWqkZljBmnkmk=.ed25519"
+
   """
 
   # ENCODE

lib/ssb_bfe/decoder.ex

@@ -6,7 +6,7 @@ defmodule SsbBfe.Decoder do
   end
 
   @doc """
-  Take a blob ID as an encoded binary, extract and encode the base64 data and return the dedoded string representing the TFD.
+  Take a blob ID as an encoded binary and return the dedoded string representing the TFD.
   """
   def decode_blob(blob_id) do
     encoded_base64_data = extract_base64_data(blob_id, <<2, 0>>)
@@ -14,95 +14,74 @@ defmodule SsbBfe.Decoder do
   end
 
   @doc """
-  Take an encrypted box as an encoded binary, extract the TF tag and call the appropriate decoder.
+  Take an encrypted box as an encoded binary and return the decoded string representind the TFD.
+
+  `decode_box/1` calls the appropriate `decode_box/2` clause based on the value of the TF tag extracted from the encoded box.
   """
   def decode_box(box) do
     tf_tag = binary_part(box, 0, 2)
     decode_box(box, tf_tag)
   end
 
-  @doc """
-  Take an encrypted box as an encoded binary and the TF tag of a box, extract and encode the base64 data and return the dedoded string representing the TFD.
-  """
   def decode_box(box, <<5, 0>>) do
     encoded_base64_data = extract_base64_data(box, <<5, 0>>)
     encoded_base64_data <> ".box"
   end
 
-  @doc """
-  Take an encrypted box as an encoded binary and the TF tag of a box2, extract and encode the base64 data and return the dedoded string representing the TFD.
-  """
   def decode_box(box, <<5, 1>>) do
     encoded_base64_data = extract_base64_data(box, <<5, 1>>)
     encoded_base64_data <> ".box2"
   end
 
   @doc """
-  Take a feed ID as an encoded binary, extract the TF tag and call the appropriate decoder.
+  Take a feed ID as an encoded binary and return the decoded string representing the TFD.
+
+  `decode_feed/1` calls the appropriate `decode_feed/2` clause based on the value of the TF tag extracted from the encoded feed.
   """
   def decode_feed(feed_id) do
     tf_tag = binary_part(feed_id, 0, 2)
     decode_feed(feed_id, tf_tag)
   end
 
-  @doc """
-  Take a feed ID as an encoded binary and the TF tag of a classic feed, extract and encode the base64 data and return the dedoded string representing the TFD.
-  """
   def decode_feed(feed_id, <<0, 0>>) do
     encoded_base64_data = extract_base64_data(feed_id, <<0, 0>>)
     "@" <> encoded_base64_data <> ".ed25519"
   end
 
   @doc """
-  Take a boolean `true` value as an encoded binary and return `true`.
+  Take an encoded generic value as an encoded binary and return `true`, `false`, `nil`, plain bytes or a decoded string.
   """
   def decode_generic(<<6, 1, 1>>), do: true
 
-  @doc """
-  Take a boolean `false` value as an encoded binary and return `false`.
-  """
   def decode_generic(<<6, 1, 0>>), do: false
 
-  @doc """
-  Take a `nil` value as an encoded binary and return `nil`.
-  """
   def decode_generic(<<6, 2>>), do: nil
 
-  @doc """
-  Take a generic value as an encoded binary, extract the TF tag and call the appropriate decoder.
-  """
   def decode_generic(generic) do
     tf_tag = binary_part(generic, 0, 2)
     decode_generic(generic, tf_tag)
   end
 
-  @doc """
-  Take a generic string as an encoded binary and the TF tag of a generic string, extract the bytes representing the string data and return the decoded string.
-  """
   def decode_generic(str, <<6, 0>>) do
     [_, str_data] = :binary.split(str, <<6, 0>>)
     str_data
   end
 
-  @doc """
-  Take generic bytes as an encoded binary and the TF tag of generic bytes, extract the bytes representing the data and return them.
-  """
   def decode_generic(bytes, <<6, 3>>) do
     [_, bytes] = :binary.split(bytes, <<6, 3>>)
     bytes
   end
 
   @doc """
-  Take a message ID as an encoded binary, extract the TF tag and call the appropriate decoder.
+  Take a message ID as an encoded binary and return the decoded string representing the TFD.
+
+  `decode_msg/1` calls the appropriate `decode_msg/2` clause based on the value of the TF tag extracted from the encoded message.
   """
   def decode_msg(msg_id) do
     tf_tag = binary_part(msg_id, 0, 2)
     decode_msg(msg_id, tf_tag)
   end
 
-  @doc """
-  Take a message ID as an encoded binary and the TF tag of a classic message, extract and encode the base64 data and return the dedoded string representing the TFD.
-  """
   def decode_msg(msg_id, <<1, 0>>) do
     encoded_base64_data = extract_base64_data(msg_id, <<1, 0>>)
     "%" <> encoded_base64_data <> ".sha256"

lib/ssb_bfe/encoder.ex

@@ -21,13 +21,10 @@ defmodule SsbBfe.Encoder do
   end
 
   @doc """
-  Take a boolean `true` value and return the encoded bytes representing the TFD.
+  Take a boolean value and return the encoded bytes representing the TFD.
   """
   def encode_bool(true), do: <<6, 1, 1>>
 
-  @doc """
-  Take a boolean `false` value and return the encoded bytes representing the TFD.
-  """
   def encode_bool(false), do: <<6, 1, 0>>
 
   @doc """