Add some documentation

src/NostrEvent.h

@@ -144,6 +144,7 @@ class SignedNostrEvent : public NostrEvent {
     bool stored;
 
   public:
+
     NostrString getId() { return this->id; }
     bool isStored() { return this->stored; }
 

src/NostrPool.h

@@ -57,23 +57,33 @@ namespace nostr {
         void processQueue();
     };
 
+    /**
+     * The main class for interacting with the Nostr network.
+     * Handles subscriptions, relays, and event publishing.
+     */
     class NostrPool {
-       private:
 
-        NostrNoticeCallback noticeCallback = nullptr;
-
-        long long subs = 0;
-        std::map<NostrString, NostrSubscription> subscriptions;
-        std::vector<NostrRelay*> relays;
-        void onEvent(NostrRelay *relay, NostrString message);
-        int eventStatusTimeoutSeconds = 60*10;
-        std::vector<EventStatusCallbackEntry>    eventStatusCallbackEntries;
-        Transport* transport;
        public:
-        NostrPool(Transport* transport,int eventStatusTimeoutSeconds=60*10) {
-            this->transport = transport;
-            this->eventStatusTimeoutSeconds = eventStatusTimeoutSeconds;
+         /**
+          * Create a new NostrPool
+          * @param transport A transport object, you can get one for the esp32 platform using nostr::esp32::ESP32Platform::getTransport() , for other platforms you need to implement the Transport
+          * interface
+          * @param eventStatusTimeoutSeconds The number of seconds to wait for an event status before timing out (optional)
+          */
+         NostrPool(Transport *transport, int eventStatusTimeoutSeconds = 60 * 10) {
+             this->transport = transport;
+             this->eventStatusTimeoutSeconds = eventStatusTimeoutSeconds;
         };
+
+        /**
+         * Subscribe to events from one or more relays
+         * @param urls The relays to subscribe to
+         * @param filters A list of filters for each relay
+         * @param eventCallback A callback to be called when an event is received (optional)
+         * @param closeCallback A callback to be called when the subscription is closed (optional)
+         * @param eoseCallback A callback to be called when the stored events are exhausted (optional) 
+         * @return The subscription ID
+         */
         NostrString subscribeMany(
             std::initializer_list<NostrString> urls,
             std::initializer_list<
@@ -84,16 +94,62 @@ namespace nostr {
             NostrEOSECallback eoseCallback = nullptr
 
         );
+
+
+        /**
+         * Publish a signed event to one or more relays. The pool will automatically start listening to the specified relays after publishing.
+         * @param rs The relays to publish to
+         * @param event The event to publish
+         * @param statusCallback A callback to be called when the event status is known (optional)
+         */
+        void publish(std::initializer_list<NostrString> rs,
+                     SignedNostrEvent *event,
+                     NostrEventStatusCallback statusCallback = nullptr);
+
+        /**
+         * Tick the NostrPool. This should be called in the main loop of your sketch
+         */
+        void loop();
+
+        /**
+         * Close the subscription with the given ID
+         * @param subId The subscription ID
+         */
         void closeSubscription(NostrString subId);
+
+        /**
+         * Ensure the connection to the specified relay is open
+         * @param url The relay URL
+         * @return The relay object
+         */
         NostrRelay *ensureRelay(NostrString url);
+
+        /**
+         * Get all relays that the pool is connected to
+         * @return A list of relay URLs
+         */
         std::vector<NostrString> getRelays();
 
+        /**
+         * Disconnect from the specified relay
+         * @param url The relay URL
+         */
         void disconnectRelay(NostrString url);
+
+        /**
+         * Close the pool and disconnect from every relay
+         */
         void close();
-        void publish(std::initializer_list<NostrString> rs,
-                     SignedNostrEvent *event,
-                     NostrEventStatusCallback statusCallback = nullptr);
-        void loop();
+
+      private:
+        NostrNoticeCallback noticeCallback = nullptr;
+        long long subs = 0;
+        std::map<NostrString, NostrSubscription> subscriptions;
+        std::vector<NostrRelay *> relays;
+        void onEvent(NostrRelay *relay, NostrString message);
+        int eventStatusTimeoutSeconds = 60 * 10;
+        std::vector<EventStatusCallbackEntry> eventStatusCallbackEntries;
+        Transport *transport;
     };
 }  // namespace nostr
 #endif

src/esp32/ESP32Platform.h

@@ -28,6 +28,9 @@ namespace nostr {
                 Serial.println(str.c_str());
             }
 
+            /**
+             * Initialize the WiFi connection
+             */
             inline void initWifi(NostrString ssid,  NostrString passphrase, int channel = 6) {
                 esp_wifi_start();
                 WiFi.begin(ssid, passphrase, channel);
@@ -42,18 +45,27 @@ namespace nostr {
                 Serial.println(WiFi.localIP());
             }
 
+            /**
+             * Initialize the time service
+             */
             inline void initTime(const char* ntpServer, long gmtOffset_sec = 0,
                                  int daylightOffset_sec = 3600) {              
                 configTime(gmtOffset_sec, daylightOffset_sec, ntpServer);
             }
 
+            /**
+             * Initialize platform specific code for the nostr library
+             */
             inline void initNostr(bool withLogger){
                 bootloader_random_enable();
                 nostr::Utils::setUnixTimeSecondsProvider(getUnixTimestamp);
                 if(withLogger)nostr::Utils::setLogger(serialLogger);
                 nostr::Utils::setRealRandom(getRealRandom);
             }
 
+            /**
+             * Get a platform specific transport 
+             */
             inline ESP32Transport* getTransport(){
                 return  new nostr::esp32::ESP32Transport();                
             }

src/services/NWC.h

@@ -41,32 +41,121 @@ template <typename T> class NWCResponseCallback : public NWCResponseCallbackBase
     std::function<void(T)> onRes = nullptr;
 };
 
+/**
+ * A class to interact with the Nostr Wallet Connect services without dealing with the underlying transport
+ */
 class NWC {
   public:
     ~NWC();
+    /**
+     * Initialize a standalone NWC service
+     * @param transport A transport object, you can get one for the esp32 platform using nostr::esp32::ESP32Platform::getTransport() , for other platforms you need to implement the Transport interface
+     * @param nwcUrl The NWC connection URL
+     */
     NWC(Transport *transport, NostrString nwcUrl);
+
+    /**
+     * Tick the main loop. This should be called in the loop() function of your sketch
+     */
     void loop();
+
+    /**
+     * Close the service, after this you should throw away the NWC object
+     */
     void close();
+
+    /**
+     * Pay a lightning invoice
+     * @param invoice The invoice to pay
+     * @param amount The amount to pay, if not specified the full amount will be paid (optional)
+     * @param onRes A callback that will be called when the payment is successful (optional)
+     * @param onErr A callback that will be called when the payment fails (optional)
+     */
     void payInvoice(NostrString invoice, unsigned long amount = static_cast<unsigned long>(-1), std::function<void(PayInvoiceResponse)> onRes = nullptr,
                     std::function<void(NostrString, NostrString)> onErr = nullptr);
+
+    /**
+     * Pay multiple lightning invoices
+     * @param invoices A list of invoices to pay
+     * @param onRes A callback that will be called when the payment is successful (nb. it will be called once for each invoice) (optional)
+     * @param onErr A callback that will be called when the payment fails (optional)
+     */
     void multiPayInvoice(std::initializer_list<Invoice> invoices, std::function<void(MultiPayInvoiceResponse)> onRes = nullptr, std::function<void(NostrString, NostrString)> onErr = nullptr);
+
+    /**
+     * Send a keysend payment
+     * @param pubkey The pubkey to send to
+     * @param amount The amount to send
+     * @param preimage The preimage to use (optional)
+     * @param tlv A list of TLV records to include (optional)
+     * @param onRes A callback that will be called when the payment is successful (optional)
+     * @param onErr A callback that will be called when the payment fails (optional) 
+     */
     void payKeySend(NostrString pubkey, unsigned long amount, NostrString preimage = "", std::initializer_list<TLVRecords> tlv = {}, std::function<void(PayKeySendResponse)> onRes = nullptr,
                     std::function<void(NostrString, NostrString)> onErr = nullptr);
 
+    /**
+     * Send multiple keysend payments
+     * @param keySends A list of keysend payments to send
+     * @param onRes A callback that will be called when the payment is successful (nb. it will be called once for each keysend) (optional)
+     * @param onErr A callback that will be called when the payment fails (optional)
+     */
     void multiPayKeySend(std::initializer_list<KeySend> keySends, std::function<void(MultiPayKeySendResponse)> onRes = nullptr, std::function<void(NostrString, NostrString)> onErr = nullptr);
 
+    /**
+     * Create a lightning invoice
+     * @param amount The amount to invoice
+     * @param description A description of the invoice (optional)
+     * @param descriptionHash A hash of the description (optional)
+     * @param expiry The expiry time of the invoice in seconds (optional)
+     * @param onRes A callback that will be called when the invoice is created (optional)
+     * @param onErr A callback that will be called when the invoice creation fails (optional)
+     */
     void makeInvoice(unsigned long amount, NostrString description = "", NostrString descriptionHash = "", unsigned long expiry = 0, std::function<void(MakeInvoiceResponse)> onRes = nullptr,
                      std::function<void(NostrString, NostrString)> onErr = nullptr);
 
+    /**
+     * Look up a payment hash
+     * @param paymentHash The payment hash to look up
+     * @param onRes A callback that will be called when the payment is found (optional)
+     * @param onErr A callback that will be called when the payment is not found (optional)
+     */
     void lookUpPaymentHash(NostrString paymentHash, std::function<void(LookUpInvoiceResponse)> onRes = nullptr, std::function<void(NostrString, NostrString)> onErr = nullptr);
 
+    /**
+     * Look up an invoice
+     * @param invoice The invoice to look up
+     * @param onRes A callback that will be called when the invoice is found (optional)
+     * @param onErr A callback that will be called when the invoice is not found (optional)
+     */
     void lookUpInvoice(NostrString invoice, std::function<void(LookUpInvoiceResponse)> onRes = nullptr, std::function<void(NostrString, NostrString)> onErr = nullptr);
 
+    /**
+     * List transactions
+     * @param from The start time of the transactions to list (optional)
+     * @param until The end time of the transactions to list (optional)
+     * @param limit The maximum number of transactions to list (optional)
+     * @param offset The offset of the transactions to list (optional)
+     * @param unpaid Whether to list only unpaid transactions (optional)
+     * @param type The type of transactions to list (optional)
+     * @param onRes A callback that will be called when the transactions are listed (optional)
+     * @param onErr A callback that will be called when the transactions listing fails (optional)
+     */
     void listTransactions(unsigned long from = 0, unsigned long until = 0, int limit = 0, int offset = 0, bool unpaid = false, NostrString type = "",
                           std::function<void(ListTransactionsResponse)> onRes = nullptr, std::function<void(NostrString, NostrString)> onErr = nullptr);
 
+    /**
+     * Get the balance
+     * @param onRes A callback that will be called when the balance is retrieved (optional)
+     * @param onErr A callback that will be called when the balance retrieval fails (optional)
+     */
     void getBalance(std::function<void(GetBalanceResponse)> onRes = nullptr, std::function<void(NostrString, NostrString)> onErr = nullptr);
 
+    /**
+     * Get the info
+     * @param onRes A callback that will be called when the info is retrieved (optional)
+     * @param onErr A callback that will be called when the info retrieval fails (optional)
+     */
     void getInfo(std::function<void(GetInfoResponse)> onRes = nullptr, std::function<void(NostrString, NostrString)> onErr = nullptr);
 
   private:
@@ -78,6 +167,6 @@ class NWC {
     NostrString accountPubKey;
     std::vector<std::unique_ptr<NWCResponseCallbackBase>> callbacks;
 };
-} // namespace nostr
+} 
 
 #endif