docs: add descriptions to all PHP files

.phpenv.php

@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * PHP environment variables.
+	 * Set PHP environment variables.
 	 */
 
 	/**

languages/language-flags.php

@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Provide language flags for hardcoded Communities.
+	 */
+
 	$server_languages = [];
 
 	// https://reccacon.com/Ukraine

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

php/generate-html.php

@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * Perform static site generation.
+	 * Generate webpages using static site generation.
 	 */
 
 	require_once 'getenv.php';

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";

php/getenv.php

@@ -1,7 +1,7 @@
 <?php
 	/**
 	 * \file
-	 * Source the project's `.phpenv.php` file.
+	 * Import project PHP environment variables.
 	 */
 
 	/**

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';

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';
 

sites/+components/communities-search.php

@@ -1,3 +1,9 @@
+<?php
+	/**
+	 * \file
+	 * Generate Community search bar.
+	 */
+?>
 <div
 	id="search-container"
 	title="Search requires JavaScript"

sites/+components/footer.php

@@ -1,3 +1,9 @@
+<?php
+	/**
+	 * \file
+	 * Generate website footer.
+	 */
+?>
 <aside id="affiliation-disclaimer">
 	<p>
 		SessionCommunities.online is not affiliated with

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

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

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">

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">

sites/+components/tbl-communities.php

@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate table of Communities.
+	 */
+
 	require_once '+components/table/table-fragment.php';
 
 	/**

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';

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';

sites/about/index.php

@@ -1,4 +1,8 @@
 <?php
+	/**
+	 * \file
+	 * Generate about page.
+	 */
 	// prerequisite include for sites
 	require_once '+getenv.php';
 ?>

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';

sites/instructions/index.php

@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate instructions page.
+	 */
+
 	require_once '+getenv.php';
 
 	$instruction_files = glob("+instructions/*.txt");

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';
 

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) {

sites/support/index.php

@@ -1,4 +1,9 @@
 <?php
+	/**
+	 * \file
+	 * Generate donation page.
+	 */
+
 	require_once '+getenv.php';
 
 	$NUM_PARTICLES = 20;