From 3792a43821abf5f5cf2bf565ec8ac4edbc06e346 Mon Sep 17 00:00:00 2001
From: gravel <gravel@noreply.codeberg.org>
Date: Tue, 6 Feb 2024 10:38:04 +0000
Subject: [PATCH] docs: add descriptions to all PHP files

---
 .phpenv.php                               | 2 +-
 languages/language-flags.php              | 5 +++++
 php/fetch-servers.php                     | 2 +-
 php/generate-html.php                     | 2 +-
 php/generate-listings.php                 | 4 +++-
 php/getenv.php                            | 2 +-
 php/update-all.php                        | 2 +-
 sites/+components/communities-json-ld.php | 5 +++++
 sites/+components/communities-search.php  | 6 ++++++
 sites/+components/footer.php              | 6 ++++++
 sites/+components/index-header.php        | 8 +++++++-
 sites/+components/issue-banner.php        | 6 ++++++
 sites/+components/page-head.php           | 4 ++++
 sites/+components/qr-modals.php           | 4 ++++
 sites/+components/tbl-communities.php     | 5 +++++
 sites/+templates/index.php                | 5 +++++
 sites/_fragment/+room-sieve.php           | 5 +++++
 sites/about/index.php                     | 4 ++++
 sites/index.php                           | 5 +++++
 sites/instructions/index.php              | 5 +++++
 sites/privacy/index.php                   | 9 ++++++---
 sites/sitemap.xml.php                     | 4 ++++
 sites/support/index.php                   | 5 +++++
 23 files changed, 95 insertions(+), 10 deletions(-)

diff --git a/.phpenv.php b/.phpenv.php
index c51cf6f..387580f 100644
--- a/.phpenv.php
+++ b/.phpenv.php
@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * PHP environment variables.
+	 * Set PHP environment variables.
 	 */
 
 	/**
diff --git a/languages/language-flags.php b/languages/language-flags.php
index 48ac039..0dfcc54 100644
--- a/languages/language-flags.php
+++ b/languages/language-flags.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Provide language flags for hardcoded Communities.
+	 */
+
 	$server_languages = [];
 
 	// https://reccacon.com/Ukraine
diff --git a/php/fetch-servers.php b/php/fetch-servers.php
index 6777758..fd6ecef 100644
--- a/php/fetch-servers.php
+++ b/php/fetch-servers.php
@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * Fetch online Communities and write the resulting data to disk.
+	 * Fetch Communities from the web.
 	 */
 
 	// requires php-curl
diff --git a/php/generate-html.php b/php/generate-html.php
index e9db596..18e099e 100644
--- a/php/generate-html.php
+++ b/php/generate-html.php
@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * Perform static site generation.
+	 * Generate webpages using static site generation.
 	 */
 
 	require_once 'getenv.php';
diff --git a/php/generate-listings.php b/php/generate-listings.php
index 2dd5abd..77ab90d 100644
--- a/php/generate-listings.php
+++ b/php/generate-listings.php
@@ -1,7 +1,9 @@
 <?php
 	/**
 	 * \file
-	 * Implement Community listings for the [Listing Provider API](https://codeberg.org/gravel/session-listing-providers).
+	 * Generate preconfigured lists of Communities.
+	 *
+	 * @see [Listing Provider API](https://codeberg.org/gravel/session-listing-providers)
 	 */
 
 	require_once "getenv.php";
diff --git a/php/getenv.php b/php/getenv.php
index 3257f93..a02a43e 100644
--- a/php/getenv.php
+++ b/php/getenv.php
@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * Source the project's `.phpenv.php` file.
+	 * Import project PHP environment variables.
 	 */
 
 	/**
diff --git a/php/update-all.php b/php/update-all.php
index 561f134..daec261 100644
--- a/php/update-all.php
+++ b/php/update-all.php
@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * Execute all jobs: Fetch Community servers, generate HTML and Community listings.
+	 * Renew all website data and assets.
 	 */
 	require_once 'fetch-servers.php';
 	require_once 'generate-html.php';
diff --git a/sites/+components/communities-json-ld.php b/sites/+components/communities-json-ld.php
index fa88c82..763ce10 100644
--- a/sites/+components/communities-json-ld.php
+++ b/sites/+components/communities-json-ld.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate structured JSON-LD site data.
+	 */
+
 	require_once '+getenv.php';
 	require_once 'php/assets/room-icons.php';
 
diff --git a/sites/+components/communities-search.php b/sites/+components/communities-search.php
index 525dbde..7f8802a 100644
--- a/sites/+components/communities-search.php
+++ b/sites/+components/communities-search.php
@@ -1,3 +1,9 @@
+<?php
+	/**
+	 * \file
+	 * Generate Community search bar.
+	 */
+?>
 <div
 	id="search-container"
 	title="Search requires JavaScript"
diff --git a/sites/+components/footer.php b/sites/+components/footer.php
index 8a59746..03453dc 100644
--- a/sites/+components/footer.php
+++ b/sites/+components/footer.php
@@ -1,3 +1,9 @@
+<?php
+	/**
+	 * \file
+	 * Generate website footer.
+	 */
+?>
 <aside id="affiliation-disclaimer">
 	<p>
 		SessionCommunities.online is not affiliated with
diff --git a/sites/+components/index-header.php b/sites/+components/index-header.php
index 65c9a52..7928e84 100644
--- a/sites/+components/index-header.php
+++ b/sites/+components/index-header.php
@@ -1,4 +1,10 @@
-<?php require_once 'php/utils/site-generation.php'; ?>
+<?php
+	/**
+	 * \file
+	 * Generate header for listing pages.
+	 */
+	require_once 'php/utils/site-generation.php';
+?>
 <header>
 	<div id="header-start">
 		<a
diff --git a/sites/+components/issue-banner.php b/sites/+components/issue-banner.php
index 0c055df..90e2c82 100644
--- a/sites/+components/issue-banner.php
+++ b/sites/+components/issue-banner.php
@@ -1,3 +1,9 @@
+<?php
+	/**
+	 * \file
+	 * Generate news banner for listing pages.
+	 */
+?>
 <div class="banner">
 	<span class="banner-note">
 		news banner
diff --git a/sites/+components/page-head.php b/sites/+components/page-head.php
index 50b6243..293fb25 100644
--- a/sites/+components/page-head.php
+++ b/sites/+components/page-head.php
@@ -1,4 +1,8 @@
 <?php
+	/**
+	 * \file
+	 * Generate preamble for current webpage.
+	 */
 	require_once 'php/utils/site-generation.php';
 ?>
 <meta charset="UTF-8">
diff --git a/sites/+components/qr-modals.php b/sites/+components/qr-modals.php
index aa02df4..45b1b55 100644
--- a/sites/+components/qr-modals.php
+++ b/sites/+components/qr-modals.php
@@ -1,4 +1,8 @@
 <?php
+	/**
+	 * \file
+	 * Generate modal to hold Community details.
+	 */
 	require_once 'php/assets/room-invites.php';
 ?>
 <dialog id="details-modal">
diff --git a/sites/+components/tbl-communities.php b/sites/+components/tbl-communities.php
index 6fd2f08..b55c06c 100644
--- a/sites/+components/tbl-communities.php
+++ b/sites/+components/tbl-communities.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate table of Communities.
+	 */
+
 	require_once '+components/table/table-fragment.php';
 
 	/**
diff --git a/sites/+templates/index.php b/sites/+templates/index.php
index 9a7c9d3..ce9e483 100644
--- a/sites/+templates/index.php
+++ b/sites/+templates/index.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate Community listing page with arbitrary list.
+	 */
+
 	require_once 'php/utils/utils.php';
 	require_once 'php/utils/site-generation.php';
 	require_once 'php/servers/servers-rooms.php';
diff --git a/sites/_fragment/+room-sieve.php b/sites/_fragment/+room-sieve.php
index 8612793..4bfe3a6 100644
--- a/sites/_fragment/+room-sieve.php
+++ b/sites/_fragment/+room-sieve.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Provide filters for Session Communities.
+	 */
+
 	require_once 'php/servers/servers-rooms.php';
 	require_once 'php/utils/utils.php';
 	require_once 'php/servers/room-listings-api.php';
diff --git a/sites/about/index.php b/sites/about/index.php
index 7f8ee19..927c321 100644
--- a/sites/about/index.php
+++ b/sites/about/index.php
@@ -1,4 +1,8 @@
 <?php
+	/**
+	 * \file
+	 * Generate about page.
+	 */
 	// prerequisite include for sites
 	require_once '+getenv.php';
 ?>
diff --git a/sites/index.php b/sites/index.php
index 9a53a74..4ac3cad 100644
--- a/sites/index.php
+++ b/sites/index.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate landing page with Community list.
+	 */
+
 	require_once '+getenv.php';
 	require_once 'php/utils/getopt.php';
 	require_once 'php/servers/room-database.php';
diff --git a/sites/instructions/index.php b/sites/instructions/index.php
index 3eb10ed..8036bea 100644
--- a/sites/instructions/index.php
+++ b/sites/instructions/index.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate instructions page.
+	 */
+
 	require_once '+getenv.php';
 
 	$instruction_files = glob("+instructions/*.txt");
diff --git a/sites/privacy/index.php b/sites/privacy/index.php
index 3a528eb..65e2455 100644
--- a/sites/privacy/index.php
+++ b/sites/privacy/index.php
@@ -1,7 +1,10 @@
 <?php
-	/*
-		If you're hosting your own version of the site, please replace this file!
-	*/
+	/**
+	 * \file
+	 * Generate privacy policy page.
+	 *
+	 * If you're hosting your own version of the site, please replace this file!
+	 */
 
 	require_once '+getenv.php';
 
diff --git a/sites/sitemap.xml.php b/sites/sitemap.xml.php
index 1bf1c13..f070c61 100644
--- a/sites/sitemap.xml.php
+++ b/sites/sitemap.xml.php
@@ -1,5 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <?php
+	/**
+	 * \file
+	 * Generate domain sitemap.
+	 */
 	require_once '+getenv.php';
 
 	function loc_lastmod(string $rel_loc, ?string $changes_under_root = null) {
diff --git a/sites/support/index.php b/sites/support/index.php
index cd329b2..16f44e2 100644
--- a/sites/support/index.php
+++ b/sites/support/index.php
@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate donation page.
+	 */
+
 	require_once '+getenv.php';
 
 	$NUM_PARTICLES = 20;