Better docstrings

Author: MadLittleMods

internal/docker/builder.go

@@ -539,6 +539,7 @@ func printPortBindingsOfAllComplementContainers(docker *client.Client, contextSt
 	log.Printf("=============== %s : END ALL COMPLEMENT DOCKER PORT BINDINGS ===============\n\n\n", contextStr)
 }
 
+// Transform the homeserver ports into the base URL and federation base URL.
 func endpoints(p nat.PortMap, hsPortBindingIP string, csPort, ssPort int) (baseURL, fedBaseURL string, err error) {
 	csapiPortBinding, err := findPortBinding(p, hsPortBindingIP, csPort)
 	if err != nil {
@@ -554,7 +555,12 @@ func endpoints(p nat.PortMap, hsPortBindingIP string, csPort, ssPort int) (baseU
 	return
 }
 
-// Find a matching port binding for the given host/port in the nat.PortMap.
+// Find a matching port binding for the given host/port in the `nat.PortMap`.
+//
+// This function will return the first port binding that matches the given host IP. If a
+// `0.0.0.0` binding is found, we will assume that it is listening on all interfaces,
+// including the `hsPortBindingIP`, and return a binding with the `hsPortBindingIP` as
+// the host IP.
 func findPortBinding(p nat.PortMap, hsPortBindingIP string, port int) (portBinding nat.PortBinding, err error) {
 	portString := fmt.Sprintf("%d/tcp", port)
 	portBindings, ok := p[nat.Port(portString)]

internal/docker/deployer.go

@@ -529,6 +529,8 @@ func assertHostnameEqual(inputUrl string, expectedHostname string) error {
 	return nil
 }
 
+// Returns URL's that are accessible from the host machine (outside the container) for
+// the homeserver's client API and federation API.
 func getHostAccessibleHomeserverUrls(ctx context.Context, docker *client.Client, containerID string, hsPortBindingIP string) (baseURL string, fedBaseURL string, err error) {
 	inspectResponse, err := inspectPortsOnContainer(ctx, docker, containerID)
 	if err != nil {
@@ -537,10 +539,10 @@ func getHostAccessibleHomeserverUrls(ctx context.Context, docker *client.Client,
 
 	baseURL, fedBaseURL, err = endpoints(inspectResponse.NetworkSettings.Ports, hsPortBindingIP, 8008, 8448)
 
-	// Sanity check that the URL's match the expected binding hostname. It's important
-	// that we use the canonical publically accessible hostname for the homeserver as ...
-	// such as important cookies that are set during a SSO/OIDC login process (cookies are
-	// scoped to the domain).
+	// Sanity check that the URL's match the expected configured binding hostname. It's
+	// also important that we use the canonical publicly accessible hostname for the
+	// homeserver for some situations like SSO/OIDC login where important cookies are set
+	// for the domain.
 	err = assertHostnameEqual(baseURL, hsPortBindingIP)
 	if err != nil {
 		return "", "", fmt.Errorf("failed to assert baseURL has the correct hostname: %w", err)
@@ -574,7 +576,8 @@ func waitForPorts(ctx context.Context, docker *client.Client, containerID string
 type ContainerInspectionError struct {
 	// Error message
 	msg string
-	// Whether this error should stop retrying to inspect the container.
+	// Indicates whether the caller should stop retrying to inspect the container because
+	// it has already exited.
 	Fatal bool
 }