From 596009c9247621550c4de8860e283a583b027edd Mon Sep 17 00:00:00 2001 From: Hugo Sales Date: Sat, 21 Mar 2020 20:18:05 +0000 Subject: [PATCH] [DOCUMENTATION] Document All The Things! --- CREDITS.md | 121 +++++++++--------- public/index.php | 30 ++++- src/Command/ListEventsCommand.php | 28 ++++ src/Controller/NetworkPublic.php | 28 ++++ .../Compiler/SchemaDefPass.php | 29 +++++ src/Entity/User.php | 28 ++++ src/Kernel.php | 28 ++++ src/Routes/Main.php | 28 ++++ src/Util/Common.php | 62 ++++++--- src/Util/ExtensionManager.php | 31 +++++ src/Util/GNUsocial.php | 82 ++++++------ src/Util/GSEvent.php | 42 ++++-- src/Util/I18n.php | 33 ++--- src/Util/Log.php | 57 +++++++++ src/Util/RouteLoader.php | 32 ++--- src/Util/SchemaDefDriver.php | 32 ++++- 16 files changed, 525 insertions(+), 166 deletions(-) diff --git a/CREDITS.md b/CREDITS.md index 0dd0a2267d..b7f5141d9f 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -6,60 +6,63 @@ StatusNet and Free Social. Apologies for any oversight; please let mail@diogo.site know if anyone's been overlooked in error. +Current team +------------ +* Alexei Sorokin +* Diogo Cordeiro +* Eliseu Amaro +* Hugo Sales + V2 team ------- * Diogo Cordeiro * Alexei Sorokin * Bruno Casteleiro -Credits for GNU social v1 ------------------------- -Leads -* Mikael Nordfeldth -* Matt Lee - Additional Contributors -* Ciaran Gultnieks -* Michael Landers -* Ori Avtalion -* Garret Buell -* Mike Cochrane -* Matthew Gregg -* Sean Murphy -* Leslie Michael Orchard -* Eric Helgeson -* Ken Sedgwick -* Brian Hendrickson -* Tobias Diekershoff -* Dan Moore -* Fil -* Jeff Mitchell -* Brenda Wallace -* Jeffery To -* Federico Marani -* mEDI -* Brett Taylor -* Brigitte Schuster -* Craig Andrews -* Donald Robertson -* Deb Nicholson -* Ian Denhart -* Steven DuBois -* Blaine Cook -* Henry Story -* Melvin Carvalho -* Stéphane Bérubé (chimo) +----------------------- * Akio -* Maiyannah Bishop +* Blaine Cook * Bob Mottram -* David Yip -* Neil E Hodges -* Moonman -* Normandy -* Verius -* Diogo Peralta Cordeiro +* Brenda Wallace +* Brett Taylor +* Brian Hendrickson +* Brigitte Schuster +* Ciaran Gultnieks +* Craig Andrews * Daniel Supernault +* Dan Moore +* David Yip +* Deb Nicholson +* Donald Robertson +* Eric Helgeson +* Federico Marani +* Fil +* Garret Buell +* Henry Story +* Ian Denhart +* Jeffery To +* Jeff Mitchell +* Ken Sedgwick +* Leslie Michael Orchard +* Maiyannah Bishop +* Matthew Gregg +* Matt Lee +* mEDI +* Melvin Carvalho +* Michael Landers * Miguel Dantas +* Mikael Nordfeldth +* Mike Cochrane +* Moonman +* Neil E Hodges +* Normandy +* Ori Avtalion +* Sean Murphy +* Stéphane Bérubé +* Steven DuBois +* Tobias Diekershoff +* Verius Credits for StatusNet -------------- @@ -68,24 +71,24 @@ Leads * Zach Copley Team -* Earle Martin -* Marie-Claude Doyon -* Sarven Capadisli -* Robin Millette -* Brion Vibber -* James Walker -* Samantha Doherty -* Florian Biree -* Erik Stambaugh -* 'drry' -* Gina Haeussge -* Tryggvi Björgvinsson * Adrian Lang -* Ori Avtalion -* Meitar Moscovitz -* Ken Sheppardson -* Simon Waters, Surevine +* Brion Vibber +* 'drry' +* Earle Martin +* Erik Stambaugh +* Florian Biree +* Gina Haeussge +* James Walker * Joshua Judson Rosen (rozzin) +* Ken Sheppardson +* Marie-Claude Doyon +* Meitar Moscovitz +* Ori Avtalion +* Robin Millette +* Samantha Doherty +* Sarven Capadisli +* Simon Waters, Surevine +* Tryggvi Björgvinsson Translators ----------- diff --git a/public/index.php b/public/index.php index 87ce437308..bf8137e5b7 100755 --- a/public/index.php +++ b/public/index.php @@ -1,5 +1,32 @@ . + */ + +/** + * GNU social's true web entry point, bootstraps Symfony's configuration and instantiates our Kernel + * + * @package GNUsocial + * @category Framework + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ use App\Kernel; use Symfony\Component\ErrorHandler\Debug; use Symfony\Component\HttpFoundation\Request; @@ -13,7 +40,8 @@ if ($_SERVER['APP_DEBUG']) { } if ($trustedProxies = $_SERVER['TRUSTED_PROXIES'] ?? $_ENV['TRUSTED_PROXIES'] ?? false) { - Request::setTrustedProxies(\explode(',', $trustedProxies), Request::HEADER_X_FORWARDED_ALL ^ Request::HEADER_X_FORWARDED_HOST); + Request::setTrustedProxies(\explode(',', $trustedProxies), + Request::HEADER_X_FORWARDED_ALL ^ Request::HEADER_X_FORWARDED_HOST); } if ($trustedHosts = $_SERVER['TRUSTED_HOSTS'] ?? $_ENV['TRUSTED_HOSTS'] ?? false) { diff --git a/src/Command/ListEventsCommand.php b/src/Command/ListEventsCommand.php index 66d4336b38..d7df4c8c66 100644 --- a/src/Command/ListEventsCommand.php +++ b/src/Command/ListEventsCommand.php @@ -1,5 +1,33 @@ . + */ + +/** + * Command to search for event by pattern + * + * @package GNUsocial + * @category Command + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\Command; use Functional as F; diff --git a/src/Controller/NetworkPublic.php b/src/Controller/NetworkPublic.php index 55760bb575..51a52ae87d 100644 --- a/src/Controller/NetworkPublic.php +++ b/src/Controller/NetworkPublic.php @@ -1,5 +1,33 @@ . + */ + +/** + * Handle network public feed + * + * @package GNUsocial + * @category Controller + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\Controller; use App\Util\GSEvent as Event; diff --git a/src/DependencyInjection/Compiler/SchemaDefPass.php b/src/DependencyInjection/Compiler/SchemaDefPass.php index 9814d5afff..f861a71ccb 100644 --- a/src/DependencyInjection/Compiler/SchemaDefPass.php +++ b/src/DependencyInjection/Compiler/SchemaDefPass.php @@ -1,5 +1,34 @@ . + */ + +/** + * Compiler pass which triggers Symgony to tell Doctrine to + * use out `SchemaDef` metadata driver + * + * @package GNUsocial + * @category DB + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\DependencyInjection\Compiler; use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface; diff --git a/src/Entity/User.php b/src/Entity/User.php index 5e52db9bc7..815a5f8c96 100644 --- a/src/Entity/User.php +++ b/src/Entity/User.php @@ -1,5 +1,33 @@ . + */ + +/** + * GNU social user ORM + * + * @package GNUsocial + * @category ORM + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\Entity; class User diff --git a/src/Kernel.php b/src/Kernel.php index 766b98bfd5..c63833381d 100644 --- a/src/Kernel.php +++ b/src/Kernel.php @@ -1,5 +1,33 @@ . + */ + +/** + * Symfony Kernel, which is responsible for configuring the whole application + * + * @package GNUsocial + * @category Kernel + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App; use App\DependencyInjection\Compiler\SchemaDefPass; diff --git a/src/Routes/Main.php b/src/Routes/Main.php index b1745bb128..20c75c3fe0 100644 --- a/src/Routes/Main.php +++ b/src/Routes/Main.php @@ -1,5 +1,33 @@ . + */ + +/** + * Define social's main routes + * + * @package GNUsocial + * @category Router + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\Routes; use App\Util\RouteLoader; diff --git a/src/Util/Common.php b/src/Util/Common.php index f5c2733e6f..49aeef9272 100644 --- a/src/Util/Common.php +++ b/src/Util/Common.php @@ -1,19 +1,32 @@ . +/* + * This file is part of GNU social - https://www.gnu.org/software/social + * + * GNU social is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * GNU social is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with GNU social. If not, see . + */ + +/** + * Common utility functions + * + * @package GNUsocial + * @category Util + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ namespace App\Util; @@ -26,6 +39,9 @@ abstract class Common { } + /** + * Normalize path by converting \ to / + */ public static function normalizePath(string $path): string { if (\DIRECTORY_SEPARATOR !== '/') { @@ -34,6 +50,9 @@ abstract class Common return $path; } + /** + * Get plugin name from it's path, or null if not a plugin + */ public static function pluginFromPath(string $path): ?string { $plug = strpos($path, '/plugins/'); @@ -52,11 +71,11 @@ abstract class Common return $final; } - public static function swapArgs($call, $arg) - { - return function ($v) use ($call, $arg) { return self::$call($v, $arg); }; - } - + /** + * Check whether $haystack starts with $needle + * + * @param array|string $haystack if array, check that all strings start with $needle + */ public static function startsWith($haystack, string $needle): bool { if (is_string($haystack)) { @@ -69,6 +88,11 @@ abstract class Common }); } + /** + * Check whether $haystack ends with $needle + * + * @param array|string $haystack if array, check that all strings end with $needle + */ public static function endsWith($haystack, string $needle) { if (is_string($haystack)) { diff --git a/src/Util/ExtensionManager.php b/src/Util/ExtensionManager.php index 3272de982c..b214dfbf1f 100644 --- a/src/Util/ExtensionManager.php +++ b/src/Util/ExtensionManager.php @@ -1,5 +1,36 @@ . + */ + +/** + * Extension loader code, one of the main features of GNU social + * + * Loads plugins from `plugins/enabled`, instances them + * and hooks its events + * + * @package GNUsocial + * @category Extensions + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\Util; use App\Util\GSEvent as Event; diff --git a/src/Util/GNUsocial.php b/src/Util/GNUsocial.php index b90b45beb9..85a8608098 100644 --- a/src/Util/GNUsocial.php +++ b/src/Util/GNUsocial.php @@ -1,19 +1,21 @@ . +/* + * This file is part of GNU social - https://www.gnu.org/software/social + * + * GNU social is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * GNU social is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with GNU social. If not, see . + */ /** * Main GNU social entry point @@ -21,33 +23,18 @@ * @package GNUsocial * @category Framework * - * @author Brenda Wallace - * @author Brion Vibber - * @author Brion Vibber - * @author Christopher Vollick - * @author CiaranG - * @author Craig Andrews - * @author Craig Andrews - * @author Evan Prodromou - * @author Evan Prodromou - * @author Evan Prodromou - * @author Evan Prodromou - * @author Gina Haeussge - * @author James Walker - * @author Jeffery To - * @author Jeffery To - * @author Mikael Nordfeldth - * @author Mike Cochrane - * @author Robin Millette - * @author Sarven Capadisli - * @author Sarven Capadisli - * @author Siebrand Mazeland - * @author Tom Adams - * @author Tom Adams - * @author Zach Copley + * StatusNet and GNU social 1 + * + * @author Refer to CREDITS.md + * @copyright 2010 Free Software Foundation, Inc http://www.fsf.org + * + * GNU social 2 + * @author Bruno Casteleiro * @author Diogo Cordeiro + * + * GNU social 3 * @author Hugo Sales - * @copyright 2010, 2018-2020 Free Software Foundation, Inc http://www.fsf.org + * @copyright 2018-2020 Free Software Foundation, Inc http://www.fsf.org * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later */ @@ -68,6 +55,9 @@ class GNUsocial implements EventSubscriberInterface protected LoggerInterface $logger; protected TranslatorInterface $translator; + /** + * Symfony dependency injection gives us access to these services + */ public function __construct(ContainerInterface $container, LoggerInterface $logger, TranslatorInterface $translator) @@ -77,6 +67,9 @@ class GNUsocial implements EventSubscriberInterface $this->translator = $translator; } + /** + * Store these services to be accessed statically and load extensions + */ public function register(EventDispatcherInterface $event_dispatcher): void { Log::setLogger($this->logger); @@ -85,6 +78,10 @@ class GNUsocial implements EventSubscriberInterface ExtensionManager::loadExtensions(); } + /** + * Event very early on in the Symfony HTTP lifecycle, but after everyting is registered + * where we get access to the event dispatcher + */ public function onKernelRequest(RequestEvent $event, string $event_name, EventDispatcherInterface $event_dispatcher): RequestEvent @@ -93,6 +90,9 @@ class GNUsocial implements EventSubscriberInterface return $event; } + /** + * Event after everything is initialized when using the `bin/console` command + */ public function onCommand(ConsoleCommandEvent $event, string $event_name, EventDispatcherInterface $event_dispatcher): ConsoleCommandEvent @@ -101,6 +101,10 @@ class GNUsocial implements EventSubscriberInterface return $event; } + /** + * Tell Symfony which events we want to listen to, which Symfony detects and autowires + * due to this implementing the `EventSubscriberInterface` + */ public static function getSubscribedEvents() { return [ diff --git a/src/Util/GSEvent.php b/src/Util/GSEvent.php index 76b018904b..7e43b4a291 100644 --- a/src/Util/GSEvent.php +++ b/src/Util/GSEvent.php @@ -1,19 +1,33 @@ . +/* + * This file is part of GNU social - https://www.gnu.org/software/social + * + * GNU social is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * GNU social is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with GNU social. If not, see . + */ + +/** + * GNU social's event handler wrapper around Symfony's, + * keeping our old interface, which is more convenient and just as powerful + * + * @package GNUsocial + * @category Event + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ namespace App\Util; diff --git a/src/Util/I18n.php b/src/Util/I18n.php index adf7280c73..af4b1c97b6 100644 --- a/src/Util/I18n.php +++ b/src/Util/I18n.php @@ -1,19 +1,21 @@ . +/* + * This file is part of GNU social - https://www.gnu.org/software/social + * + * GNU social is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * GNU social is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with GNU social. If not, see . + */ /** * Utility functions for i18n @@ -25,7 +27,8 @@ * @author Ciaran Gultnieks * @author Evan Prodromou * @author Diogo Cordeiro - * @copyright 2010, 2019 Free Software Foundation, Inc http://www.fsf.org + * @author Hugo Sales + * @copyright 2010, 2018-2020 Free Software Foundation, Inc http://www.fsf.org * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later */ diff --git a/src/Util/Log.php b/src/Util/Log.php index f24a838d88..2e6875a1b5 100644 --- a/src/Util/Log.php +++ b/src/Util/Log.php @@ -1,5 +1,34 @@ . + */ + +/** + * GNU social's logger wrapper around Symfony's, + * keeping our old static interface, which is more convenient and just as powerful + * + * @package GNUsocial + * @category Log + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\Util; use Psr\Log\LoggerInterface; @@ -13,11 +42,39 @@ class Log self::$logger = $l; } + /** + * Simple static wrappers around Monolog's functions + */ + public static function emergency(string $msg): void + { + self::$logger->emergency($msg); + } + + public static function alert(string $msg): void + { + self::$logger->alert($msg); + } + + public static function critical(string $msg): void + { + self::$logger->critical($msg); + } + public static function error(string $msg): void { self::$logger->error($msg); } + public static function warning(string $msg): void + { + self::$logger->warning($msg); + } + + public static function notice(string $msg): void + { + self::$logger->notice($msg); + } + public static function info(string $msg): void { self::$logger->info($msg); diff --git a/src/Util/RouteLoader.php b/src/Util/RouteLoader.php index 1b22de9d2d..310a63445e 100644 --- a/src/Util/RouteLoader.php +++ b/src/Util/RouteLoader.php @@ -1,22 +1,24 @@ . +/* + * This file is part of GNU social - https://www.gnu.org/software/social + * + * GNU social is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * GNU social is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with GNU social. If not, see . + */ /** - * Old URLMapper interface atop Symfony's router + * Dynamic router loader and URLMapper interface atop Symfony's router * * Converts a path into a set of parameters, and vice versa * diff --git a/src/Util/SchemaDefDriver.php b/src/Util/SchemaDefDriver.php index f0d5329c63..5bc085a931 100644 --- a/src/Util/SchemaDefDriver.php +++ b/src/Util/SchemaDefDriver.php @@ -1,5 +1,33 @@ . + */ + +/** + * Doctrine metadata driver which implements our old `schemaDef` interface + * + * @package GNUsocial + * @category DB + * + * @author Hugo Sales + * @copyright 2020 Free Software Foundation, Inc http://www.fsf.org + * @license https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later + */ + namespace App\Util; use Doctrine\Persistence\Mapping\ClassMetadata; @@ -118,10 +146,6 @@ class SchemaDefDriver extends StaticPHPDriver /** * Convert [$key => $val] to ['name' => $key, 'columns' => $val] - * - * @param array - * - * @return array */ private static function kv_to_name_col(array $arr): array {