Add some miscellaneous documentation

This commit adds some documentation to miscellaneous functions and
classes.

Signed-off-by: Daniel D’Aquino <daniel@daquino.me>

damus/Models/Contacts+.swift

@@ -79,7 +79,8 @@ func remove_relay(ev: NostrEvent, current_relays: [RelayDescriptor], keypair: Fu
     return NostrEvent(content: content, keypair: keypair.to_keypair(), kind: 3, tags: ev.tags.strings())
 }
 
-func add_relay(ev: NostrEvent, keypair: FullKeypair, current_relays: [RelayDescriptor], relay: RelayURL, info: RelayInfo) -> NostrEvent? {
+/// Handles the creation of a new `kind:3` contact list based on a previous contact list, with the specified relays
+func add_relay(ev: NostrEvent, keypair: FullKeypair, current_relays: [RelayDescriptor], relay: RelayURL, info: RelayRWConfiguration) -> NostrEvent? {
     var relays = ensure_relay_info(relays: current_relays, content: ev.content)
     
     // If kind:3 content is empty, or if the relay doesn't exist in the list,

damus/Nostr/NostrKind.swift

@@ -8,6 +8,7 @@
 import Foundation
 
 
+/// A known Nostr event kind, addressable by name, with the actual number assigned by the protocol as the value
 enum NostrKind: UInt32, Codable {
     case metadata = 0
     case text = 1

damus/Nostr/NostrRequest.swift

@@ -12,11 +12,14 @@ struct NostrSubscribe {
     let sub_id: String
 }
 
-
+/// Models a request/message that is sent to a Nostr relay
 enum NostrRequestType {
+    /// A standard nostr request
     case typical(NostrRequest)
+    /// A customized nostr request. Generally used in the context of a nostrscript.
     case custom(String)
     
+    /// Whether this request is meant to write data to a relay
     var is_write: Bool {
         guard case .typical(let req) = self else {
             return true
@@ -25,6 +28,7 @@ enum NostrRequestType {
         return req.is_write
     }
     
+    /// Whether this request is meant to read data from a relay
     var is_read: Bool {
         guard case .typical(let req) = self else {
             return true
@@ -34,12 +38,18 @@ enum NostrRequestType {
     }
 }
 
+/// Models a standard request/message that is sent to a Nostr relay.
 enum NostrRequest {
+    /// Subscribes to receive information from the relay
     case subscribe(NostrSubscribe)
+    /// Unsubscribes from an existing subscription, addressed by its id
     case unsubscribe(String)
+    /// Posts an event
     case event(NostrEvent)
+    /// Authenticate with the relay
     case auth(NostrEvent)
 
+    /// Whether this request is meant to write data to a relay
     var is_write: Bool {
         switch self {
         case .subscribe:
@@ -53,6 +63,7 @@ enum NostrRequest {
         }
     }
     
+    /// Whether this request is meant to read data from a relay
     var is_read: Bool {
         return !is_write
     }

damus/Nostr/ReferencedId.swift

@@ -115,6 +115,19 @@ enum FollowRef: TagKeys, Hashable, TagConvertible, Equatable {
     }
 }
 
+/// Models common tag references defined by the Nostr protocol, and their associated values.
+///
+/// For example, this raw JSON tag sequence:
+/// ```json
+///   ["p", "8b2be0a0ad34805d76679272c28a77dbede9adcbfdca48c681ec8b624a1208a6"]
+/// ```
+///
+/// would be parsed into something equivalent to `.pubkey(Pubkey(hex: "8b2be0a0ad34805d76679272c28a77dbede9adcbfdca48c681ec8b624a1208a6"))`
+///
+/// ## Notes
+///
+/// - Not all tag information from all NIPs can be modelled using this alone, as some NIPs may define extra associated values for specific event types. You may need to use a specialized type for some event kinds
+///
 enum RefId: TagConvertible, TagKeys, Equatable, Hashable {
     case event(NoteId)
     case pubkey(Pubkey)
@@ -124,6 +137,7 @@ enum RefId: TagConvertible, TagKeys, Equatable, Hashable {
     case naddr(NAddr)
     case reference(String)
     
+    /// The key that defines the type of reference being made
     var key: RefKey {
         switch self {
         case .event:        return .e
@@ -136,6 +150,14 @@ enum RefId: TagConvertible, TagKeys, Equatable, Hashable {
         }
     }
 
+    /// Defines the type of reference being made on a Nostr event tag
+    ///
+    /// Example:
+    /// ```json
+    ///   ["p", "8b2be0a0ad34805d76679272c28a77dbede9adcbfdca48c681ec8b624a1208a6"]
+    /// ```
+    ///
+    /// The `RefKey` is "p"
     enum RefKey: AsciiCharacter, TagKey, CustomStringConvertible {
         case e, p, t, d, q, a, r
 
@@ -148,10 +170,12 @@ enum RefId: TagConvertible, TagKeys, Equatable, Hashable {
         }
     }
 
+    /// A raw nostr-style tag sequence representation of this object
     var tag: [String] {
         [self.key.description, self.description]
     }
     
+    /// Describes what is being referenced, as a `String`
     var description: String {
         switch self {
         case .event(let noteId): return noteId.hex()
@@ -166,6 +190,7 @@ enum RefId: TagConvertible, TagKeys, Equatable, Hashable {
         }
     }
 
+    /// Parses a raw tag sequence
     static func from_tag(tag: TagSequence) -> RefId? {
         var i = tag.makeIterator()
 

damus/Nostr/RelayPool.swift

@@ -24,6 +24,7 @@ struct SeenEvent: Hashable {
     let evid: NoteId
 }
 
+/// Establishes and manages connections and subscriptions to a list of relays.
 class RelayPool {
     var relays: [Relay] = []
     var handlers: [RelayHandler] = []
@@ -31,6 +32,7 @@ class RelayPool {
     var seen: Set<SeenEvent> = Set()
     var counts: [RelayURL: UInt64] = [:]
     var ndb: Ndb
+    /// The keypair used to authenticate with relays
     var keypair: Keypair?
     var message_received_function: (((String, RelayDescriptor)) -> Void)?
     var message_sent_function: (((String, Relay)) -> Void)?
@@ -243,19 +245,19 @@ class RelayPool {
     func send_raw(_ req: NostrRequestType, to: [RelayURL]? = nil, skip_ephemeral: Bool = true) {
         let relays = to.map{ get_relays($0) } ?? self.relays
 
-        self.send_raw_to_local_ndb(req)
+        self.send_raw_to_local_ndb(req)     // Always send Nostr events and data to NostrDB for a local copy
 
         for relay in relays {
             if req.is_read && !(relay.descriptor.info.read ?? true) {
-                continue
+                continue    // Do not send read requests to relays that are not READ relays
             }
             
             if req.is_write && !(relay.descriptor.info.write ?? true) {
-                continue
+                continue    // Do not send write requests to relays that are not WRITE relays
             }
             
             if relay.descriptor.ephemeral && skip_ephemeral {
-                continue
+                continue    // Do not send requests to ephemeral relays if we want to skip them
             }
             
             guard relay.connection.isConnected else {

damus/Util/Relays/RelayModelCache.swift

@@ -7,6 +7,13 @@
 
 import Foundation
 
+/// Stores information, metadata, and logs about different relays. Generally used as a singleton.
+///
+/// # Discussion
+///
+/// This class is primarily used as a shared singleton in `DamusState`, to allow other parts of the app to access information, metadata, and logs about relays without having to fetch it themselves.
+///
+/// For example, it is used by `RelayView` to supplement information about the relay without having to fetch those again from the network, as well as to display logs collected throughout the use of the app.
 final class RelayModelCache: ObservableObject {
     private var models = [RelayURL: RelayModel]()
     

nostrdb/NdbTagIterator.swift

@@ -7,6 +7,18 @@
 
 import Foundation
 
+
+/// The sequence of strings in a single nostr event tag
+///
+/// Example 1:
+/// ```json
+///   ["r", "wss://nostr-relay.example.com", "read"]
+/// ```
+///
+/// Example 2:
+/// ```json
+///   ["p", "8b2be0a0ad34805d76679272c28a77dbede9adcbfdca48c681ec8b624a1208a6"]
+/// ```
 struct TagSequence: Sequence {
     let note: NdbNote
     let tag: UnsafeMutablePointer<ndb_tag>