From f526f859a5b15cc19c4bde882c620fa06f21f8ea Mon Sep 17 00:00:00 2001
From: Tyler Beckman <ty@myriation.xyz>
Date: Sun, 27 Oct 2024 16:03:40 -0600
Subject: [PATCH] docs(api): List outputs in CtApiClient methods

---
 src/api/mod.rs | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/src/api/mod.rs b/src/api/mod.rs
index 8f158a3..d153df8 100644
--- a/src/api/mod.rs
+++ b/src/api/mod.rs
@@ -23,7 +23,9 @@ impl CtApiClient {
 		})
 	}
 
-	/// Adds a standard x509 chain to the CT log.
+	/// Adds a standard x509 chain to the CT log. The log will then return
+	/// information needed to construct a valid SCT entry, including timestamp,
+	/// CT log signature, sct version, and any log operator extensions.
 	///
 	/// See: [`endpoints::ADD_CHAIN`]
 	///
@@ -54,6 +56,7 @@ impl CtApiClient {
 	/// Adds a precetificate chain to the CT log. This is largely the same as
 	/// [`CtApiClient::add_chain`], except is used specifically when the chain
 	/// starts with a precertificate rather than the final end-user certificate.
+	/// Response data is exactly the same as [`CtApiClient::add_chain`].
 	///
 	/// See: [`endpoints::ADD_PRE_CHAIN`]
 	///
@@ -84,7 +87,11 @@ impl CtApiClient {
 			.await
 	}
 
-	/// Fetches the Signed Tree Head information for the current CT log tree
+	/// Fetches the Signed Tree Head information for the current CT log tree.
+	/// The response contains the tree size, timestamp, root hash, and a
+	/// signature of all of the above from the CT log. This data can be used to
+	/// verify the integrity of the tree at any point, and verify inclusion of a
+	/// leaf in the tree.
 	///
 	/// See: [`endpoints::GET_STH`]
 	///
@@ -106,7 +113,9 @@ impl CtApiClient {
 	}
 
 	/// Fetches the Signed Tree Head consistency proof for a specified start
-	/// tree_size and end tree_size.
+	/// tree_size and end tree_size. This consistency proof is simply a list of
+	/// each merkle tree node necessary to verify the append-only nature of the
+	/// log between the specified first and second tree sizes.
 	///
 	/// See: [`endpoints::GET_STH_CONSISTENCY`]
 	///
@@ -138,7 +147,7 @@ impl CtApiClient {
 	/// Fetches a single merkle audit proof for a specific leaf node by hash
 	/// from the CT log. The response both includes the index of the hashed
 	/// leaf node and the list of Merkle Tree nodes required to verify proof of
-	/// existence.
+	/// existence of your specified node in the full tree.
 	///
 	/// See: [`endpoints::GET_PROOF_BY_HASH`]
 	///