add doc comments

libp2p/services/wildcardresolverservice.nim

@@ -24,6 +24,9 @@ logScope:
 type
   WildcardAddressResolverService* = ref object of Service
     ## Service used to resolve wildcard addresses of the type "0.0.0.0" for IPv4 or "::" for IPv6.
+    ## When used with a `Switch`, this service will be automatically started and stopped
+    ## when the switch starts and stops. This is facilitated by adding the service to the switch's
+    ## list of services using the `.withServices(@[svc])` method in the `SwitchBuilder`.
     networkInterfaceProvider: NetworkInterfaceProvider
     ## Provides a list of network addresses.
     addressMapper: AddressMapper
@@ -69,6 +72,16 @@ proc new*(
     scheduleInterval: Opt[Duration] = Opt.none(Duration),
     networkInterfaceProvider: NetworkInterfaceProvider = new(NetworkInterfaceProvider),
 ): T =
+  ## This procedure initializes a new `WildcardAddressResolverService` with the provided
+  ## schedule interval and network interface provider.
+  ##
+  ## Parameters:
+  ## - `T`: The type descriptor for `WildcardAddressResolverService`.
+  ## - `scheduleInterval`: An optional interval at which the service should run. Defaults to none.
+  ## - `networkInterfaceProvider`: A provider that offers access to network interfaces. Defaults to a new instance of `NetworkInterfaceProvider`.
+  ##
+  ## Returns:
+  ## - A new instance of `WildcardAddressResolverService`.
   return T(
     scheduleInterval: scheduleInterval,
     networkInterfaceProvider: networkInterfaceProvider,
@@ -77,6 +90,15 @@ proc new*(
 proc schedule(
     service: WildcardAddressResolverService, switch: Switch, interval: Duration
 ) {.async.} =
+  ## Schedules the WildcardAddressResolverService to run at regular intervals.
+  ##
+  ## Sets up a schedule for the WildcardAddressResolverService to execute periodically based
+  ## on the specified interval. It continuously runs the service on the given switch at the defined time intervals.
+  ##
+  ## Parameters:
+  ## - `service`: The instance of the WildcardAddressResolverService that will be scheduled.
+  ## - `switch`: The Switch object that the service will operate on.
+  ## - `interval`: The Duration specifying how often the service should run.
   heartbeat "Scheduling WildcardAddressResolverService run", interval:
     await service.run(switch)
 
@@ -177,6 +199,17 @@ proc expandWildcardAddresses(
 method setup*(
     self: WildcardAddressResolverService, switch: Switch
 ): Future[bool] {.async.} =
+  ## Sets up the `WildcardAddressResolverService`.
+  ##
+  ## This method adds the address mapper to the peer's list of address mappers and schedules the seervice to run
+  ## at the specified interval.
+  ##
+  ## Parameters:
+  ## - `self`: The instance of `WildcardAddressResolverService` being set up.
+  ## - `switch`: The switch context in which the service operates.
+  ##
+  ## Returns:
+  ## - A `Future[bool]` that resolves to `true` if the setup was successful, otherwise `false`.
   self.addressMapper = proc(
       listenAddrs: seq[MultiAddress]
   ): Future[seq[MultiAddress]] {.async.} =
@@ -194,12 +227,29 @@ method setup*(
   return hasBeenSetup
 
 method run*(self: WildcardAddressResolverService, switch: Switch) {.async, public.} =
+  ## Runs the WildcardAddressResolverService for a given switch.
+  ##
+  ## It updates the peer information for the provided switch by running the registered address mapper. Any other
+  ## address mappers that are registered with the switch will also be run.
+  ##
   trace "Running WildcardAddressResolverService"
   await switch.peerInfo.update()
 
 method stop*(
     self: WildcardAddressResolverService, switch: Switch
 ): Future[bool] {.async, public.} =
+  ## Stops the WildcardAddressResolverService.
+  ##
+  ## Handles the shutdown process of the WildcardAddressResolverService for a given switch.
+  ## It cancels the scheduled task, if any, and removes the address mapper from the switch's list of address mappers.
+  ## It then updates the peer information for the provided switch. Any wildcard address wont be resolved anymore.
+  ##
+  ## Parameters:
+  ## - `self`: The instance of the WildcardAddressResolverService.
+  ## - `switch`: The Switch object associated with the service.
+  ##
+  ## Returns:
+  ## - A future that resolves to `true` if the service was successfully stopped, otherwise `false`.
   debug "Stopping WildcardAddressResolverService"
   let hasBeenStopped = await procCall Service(self).stop(switch)
   if hasBeenStopped: