From f04b625c7b14ef39f9993968b3e20a88b8dab2e9 Mon Sep 17 00:00:00 2001
From: gravel <gravel@noreply.codeberg.org>
Date: Tue, 6 Feb 2024 09:59:55 +0000
Subject: [PATCH] docs: update class documentation

---
 php/servers/room-database.php     | 3 +++
 php/servers/room-listings-api.php | 6 +++++-
 php/servers/servers-rooms.php     | 4 ++--
 php/servers/sources.php           | 8 ++++----
 php/servers/tags.php              | 7 +++++--
 php/utils/fetching-coroutines.php | 4 ++--
 php/utils/logging.php             | 4 ++--
 php/utils/site-generation.php     | 3 +++
 sites/_fragment/+room-sieve.php   | 3 +++
 9 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/php/servers/room-database.php b/php/servers/room-database.php
index 4e0cd8a..67213a4 100644
--- a/php/servers/room-database.php
+++ b/php/servers/room-database.php
@@ -1,6 +1,9 @@
 <?php
 	require_once "servers/servers-rooms.php";
 
+	/**
+	 * Stores Communities and Community servers.
+	 */
 	class CommunityDatabase {
 		private function __construct(array $servers) {
 			$this->servers = $servers;
diff --git a/php/servers/room-listings-api.php b/php/servers/room-listings-api.php
index 202423b..4b7db7d 100644
--- a/php/servers/room-listings-api.php
+++ b/php/servers/room-listings-api.php
@@ -1,4 +1,8 @@
 <?php
+
+	/**
+	 * Parses configured lists of Communities
+	 */
 	class CommunityListingDatabase {
 		private array $listings;
 
@@ -61,7 +65,7 @@
 	}
 
 	/**
-	 * Represents a Community listing in the Listing Provider API.
+	 * Lists Communities from a configured list.
 	 */
 	class CommunityListing implements JsonSerializable {
 		/**
diff --git a/php/servers/servers-rooms.php b/php/servers/servers-rooms.php
index 22bb915..204fd5f 100644
--- a/php/servers/servers-rooms.php
+++ b/php/servers/servers-rooms.php
@@ -13,7 +13,7 @@
 	require_once 'utils/numeric.php';
 
 	/**
-	 * Representation of Session Community room.
+	 * Represents a Session Community.
 	 */
 	class CommunityRoom implements JsonSerializable {
 		/**
@@ -797,7 +797,7 @@
 	}
 
 	/**
-	 * Class representing Session Community server hosting Community rooms.
+	 * Represents a Session Open Group Server.
 	 */
 	class CommunityServer implements JsonSerializable {
 		/**
diff --git a/php/servers/sources.php b/php/servers/sources.php
index 7c0c80c..6568f94 100644
--- a/php/servers/sources.php
+++ b/php/servers/sources.php
@@ -3,7 +3,7 @@
 	require_once 'servers/tags.php';
 
 	/**
-	 * Describes a type of source capable of producing a per-Community tag list.
+	 * Provides tags for Session Communities.
 	 */
 	interface CommunitySourceWithTags {
 		/**
@@ -14,7 +14,7 @@
 	}
 
 	/**
-	 * Encapsulates Community data fetched from https://session.directory/.
+	 * Parses Communities fetched from Session.directory.
 	 */
 	class SDIRCommunitySource implements CommunitySourceWithTags {
 		private function __construct(string $contents) {
@@ -127,7 +127,7 @@
 	}
 
 	/**
-	 * Encapsulates Community data fetched from [Awesome-Session-Group-List](https://raw.githubusercontent.com/GNU-Linux-libre/Awesome-Session-Group-List/main/README.md).
+	 * Parses Communities fetched from [Awesome-Session-Group-List](https://raw.githubusercontent.com/GNU-Linux-libre/Awesome-Session-Group-List/main/README.md).
 	 */
 	class ASGLCommunitySource implements CommunitySourceWithTags {
 		private function __construct(string $contents) {
@@ -216,7 +216,7 @@
 	}
 
 	/**
-	 * Encapsulates sources of Communities found on the web.
+	 * Finds Communities on the web.
 	 */
 	class CommunitySources {
 		private const SOURCES = array(
diff --git a/php/servers/tags.php b/php/servers/tags.php
index 8b59678..073317e 100644
--- a/php/servers/tags.php
+++ b/php/servers/tags.php
@@ -7,7 +7,7 @@
 	require_once 'utils/utils.php';
 
 	/**
-	 * Class enumerating types of Community tags.
+	 * Enumerates types of labels applied to Communities.
 	 */
 	class TagType {
 		private function __construct() {}
@@ -26,7 +26,7 @@
 	}
 
 	/**
-	 * Represents a manual or derived Community tag.
+	 * Represents a label applied to Communities
 	 */
 	class CommunityTag implements JsonSerializable {
 		/**
@@ -281,6 +281,9 @@
 		}
 	}
 
+	/**
+	 * Constructs Community tags reserved by the aggregator.
+	 */
 	class ReservedTags {
 		public static function official() {
 			$CHECK_MARK = "✅";
diff --git a/php/utils/fetching-coroutines.php b/php/utils/fetching-coroutines.php
index eccf515..3dd8c59 100644
--- a/php/utils/fetching-coroutines.php
+++ b/php/utils/fetching-coroutines.php
@@ -6,7 +6,7 @@
 	require_once 'utils/utils.php';
 
 	/**
-	 * Class handling execution of network overhead coroutine.
+	 * Runs a coroutine with network yielding
 	 *
 	 * @template TReturn
 	 */
@@ -255,7 +255,7 @@
 	}
 
 	/**
-	 * Class responsible for running multiple FetchingCoroutines concurrently.
+	 * Runs multiple coroutines with network yielding
 	 */
 	class FetchingCoroutineRunner {
 		/**
diff --git a/php/utils/logging.php b/php/utils/logging.php
index ff9615d..5d542bb 100644
--- a/php/utils/logging.php
+++ b/php/utils/logging.php
@@ -17,10 +17,10 @@
 	$NANOSEC = 1E9;
 
 	/**
-	 * Comparable enum describing the verbosity of logged messages.
+	 * Describes verbosity levels of diagnostic logs.
 	 */
 	final class LoggingVerbosity {
-		// Make class functionally static.
+		// Prevent class instantiation
 		private function __construct() {}
 
 		const Error = 10;
diff --git a/php/utils/site-generation.php b/php/utils/site-generation.php
index 4d31562..0c91920 100644
--- a/php/utils/site-generation.php
+++ b/php/utils/site-generation.php
@@ -1,5 +1,8 @@
 <?php
 
+	/**
+	 * Provides site generation context variables.
+	 */
 	class SiteGeneration {
 		public static function getCanonicalPageURL() {
 			global $SITE_CANONICAL_URL;
diff --git a/sites/_fragment/+room-sieve.php b/sites/_fragment/+room-sieve.php
index d713469..8612793 100644
--- a/sites/_fragment/+room-sieve.php
+++ b/sites/_fragment/+room-sieve.php
@@ -3,6 +3,9 @@
 	require_once 'php/utils/utils.php';
 	require_once 'php/servers/room-listings-api.php';
 
+	/**
+	 * Filters Session Communities.
+	 */
 	class RoomSieve {
 		/**
 		 * @var CommunityRoom[] $rooms;