[modular][promise] Add more documentation and example to ledger_client fit::promise wrappers.
TEST=none
Change-Id: I807e3b4d64516fb15c2cdc47b5d6da9efc9b27e8
diff --git a/lib/ledger_client/promise.h b/lib/ledger_client/promise.h
index 4947d75..23f3fa9 100644
--- a/lib/ledger_client/promise.h
+++ b/lib/ledger_client/promise.h
@@ -12,10 +12,30 @@
namespace modular {
-// fit::promise wrapper functions for fuchsia.ledger.Page.
+// These wrapper functions wrap fuchsia.ledger APIs such that they return
+// a fit::promise<> representing the result of the call. They are useful to
+// incorporate into tasks themselves expressed as fit::promises.
//
-// These methods match the signatures in fuchsia.ledger.Page with the exception
-// that the first parameter is always a fuchsia::ledger::Page*.
+// The wrapper classes act as namespaces for static methods. For a given api
+// (such as fuchsia.ledger.Page), the wrapper class is called PagePromise, and
+// each method has the same signature as that in fuchsia::ledger::Page, with the
+// addition that the first parameter is always a fuchsia::ledger::Page* and the
+// last parameter (the result callback) is omitted.
+//
+// Note that these wrapper methods IMMEDIATELY call the underlying FIDL
+// function (meaning that a message is dispatched immediately on the underlying
+// channel). The returned promise will block until a response message is
+// received.
+//
+// EXAMPLE
+//
+// auto p = fit::make_promise([snapshot = page_snapshot_ptr.get()] () {
+// return PageSnapshotPromise::GetInline(snapshot, key);
+// }).and_then([] (const std::vector<uint8_t> bytes) {
+// // Decode and use |bytes|.
+// });
+
+// fit::promise wrapper functions for fuchsia.ledger.Page.
class PagePromise {
public:
static fit::promise<> StartTransaction(fuchsia::ledger::Page* page) {
@@ -125,7 +145,7 @@
FXL_LOG(FATAL) << "TODO: fallback to PageSnapshot_Get().";
default:
FXL_LOG(ERROR) << "PageSnapshotPromise::GetInline() failed with "
- << fidl::ToUnderlying(status);
+ << fidl::ToUnderlying(status);
completer.complete_error();
}
});
