docs: Improve "Entry points" documentation page

Turn this into a doc group, and let the descriptions come
directly from the files in question. This makes the list easier
to maintain, and alsom means that the overview page becomes
discoverable whenever one is looking at the entry point file
as well. Previously the doc page pointed to the entry points,
but not the other way around. This is also fixed.

Bug: T244294
Change-Id: I891c5a37e17592edc1136d7367949927121c8bc8

api.php

@@ -1,6 +1,10 @@
 <?php
 /**
- * This file is the entry point for all API queries.
+ * The web entry point for all Action API queries.
+ *
+ * This is used by bots to fetch content and information about the wiki,
+ * its pages, and its users. See <https://www.mediawiki.org/wiki/API> for more
+ * information.
  *
  * It begins by constructing a new ApiMain using the parameter passed to it
  * as an argument in the URL ('?action='). It then invokes "execute()" on the
@@ -25,6 +29,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup entrypoint
  */
 
 use MediaWiki\Logger\LegacyLogger;

docs/scripts.md

@@ -1,41 +0,0 @@
-Scripts
-=======
-
-MediaWiki primary scripts are in the root directory of the software. Users
-should only use these scripts to access the wiki. There are also some `.php` that
-aren't primary scripts but helper files and won't work if they are accessed
-directly by the web.
-
-Primary scripts:
-----------------
-
-  - index.php
-
-    Main access point. It handles the most of requests.
-    See <https://www.mediawiki.org/wiki/Manual:Index.php>
-
-  - api.php
-
-    Script to provide an API for bots to fetch content and informations about
-    the site and also modify it. See <https://www.mediawiki.org/wiki/API>
-    for more information.
-
-  - img_auth.php
-
-    Script that only serve images to logged in users. To configure the wiki
-    to use that script, see <https://www.mediawiki.org/wiki/Manual:Image_Authorisation>.
-
-  - load.php
-
-    Used by `ResourceLoader` to serve minified, concatenated and gzipped CSS and JS.
-
-  - opensearch_desc.php
-
-    Returns a OpenSearch description document (see <http://www.opensearch.org/>)
-    that points to the search engines of the wiki.
-
-  - thumb.php
-
-    Script used to resize images if it is configured to be done when the web
-    browser requests the image and not when generating the page. This script can
-    be used as a 404 handler to generate image thumbs when they don't exist.

img_auth.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Image authorisation script
+ * The web entry point for serving non-public images to logged-in users.
  *
  * To use this, see https://www.mediawiki.org/wiki/Manual:Image_Authorization
  *
@@ -36,6 +36,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup entrypoint
  */
 
 define( 'MW_NO_OUTPUT_COMPRESSION', 1 );

includes/DefaultSettings.php

@@ -1309,11 +1309,24 @@ $wgAttemptFailureEpoch = 1;
 $wgIgnoreImageErrors = false;
 
 /**
- * Allow thumbnail rendering on page view. If this is false, a valid
- * thumbnail URL is still output, but no file will be created at
- * the target location. This may save some time if you have a
- * thumb.php or 404 handler set up which is faster than the regular
- * webserver(s).
+ * Render thumbnails while parsing wikitext.
+ *
+ * If set to false, then the Parser will output valid thumbnail URLs without
+ * generating or storing the thumbnail files. This can significantly speed up
+ * processing on the web server. The site admin needs to configure a 404 handler
+ * in order for the URLs in question to regenerate the thumbnails in question
+ * on-demand. This can enable concurrency and also save computing resources
+ * as not every resolution of every image on every page is accessed between
+ * re-parses of the article. For example, re-parses triggered by bot edits,
+ * or cascading updates from template edits.
+ *
+ * If you use $wgLocalFileRepo, then you will also need to set the following:
+ *
+ * @code
+ *   $wgLocalFileRepo['transformVia404'] = true;
+ * @endcode
+ * @var bool
+ * @since 1.7.0
  */
 $wgGenerateThumbnailOnParse = true;
 

includes/WebStart.php

@@ -25,6 +25,14 @@
  * @file
  */
 
+/**
+ * @defgroup entrypoint Entry points
+ *
+ * These primary scripts live in the root directory. They are the ones used by
+ * web requests to interact with the wiki. Other PHP files in the repository
+ * do not need to be accessed directly by the web.
+ */
+
 # T17461: Make IE8 turn off content sniffing. Everybody else should ignore this
 # We're adding it here so that it's *always* set, even for alternate entry
 # points and when $wgOut gets disabled or overridden.

index.php

@@ -1,18 +1,18 @@
-<?php
+<?php // For broken web servers: ><pre>
+
+// If you are reading this in your web browser, your server is probably
+// not configured correctly to run PHP applications!
+//
+// See the README, INSTALL, and UPGRADE files for basic setup instructions
+// and pointers to the online documentation.
+//
+// https://www.mediawiki.org/wiki/Special:MyLanguage/MediaWiki
+//
+// -------------------------------------------------
+
 /**
- * For people without PHP, close tag for easier debugging: ><pre>
- *
- * This is the main web entry point for MediaWiki.
- *
- * If you are reading this in your web browser, your server is probably
- * not configured correctly to run PHP applications!
- *
- * See the README, INSTALL, and UPGRADE files for basic setup instructions
- * and pointers to the online documentation.
- *
- * https://www.mediawiki.org/wiki/Special:MyLanguage/MediaWiki
- *
- * ----------
+ * The main web entry point for MediaWiki. It handles all web requests for
+ * navigations from web browsers.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -30,6 +30,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup entrypoint
  */
 
 define( 'MW_ENTRY_POINT', 'index' );

load.php

@@ -1,6 +1,7 @@
 <?php
 /**
- * This file is the entry point for ResourceLoader.
+ * The web entry point for ResourceLoader. It serves static CSS and JavaScript
+ * assets for web browsers.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -18,6 +19,8 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup entrypoint
+ * @ingroup ResourceLoader
  * @author Roan Kattouw
  * @author Trevor Parscal
  */

opensearch_desc.php

@@ -1,6 +1,11 @@
 <?php
 /**
- * Generate an OpenSearch description file.
+ * The web entry point for generating an OpenSearch description document.
+ *
+ * See <http://www.opensearch.org/> for the specification of the OpenSearch
+ * "description" document. In a nut shell, this tells browsers how and where
+ * to submit submit search queries to get a search results page back,
+ * as well as how to get typeahead suggestions (see ApiOpenSearch).
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -18,6 +23,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup entrypoint
  */
 
 // This endpoint is supposed to be independent of request cookies and other

thumb.php

@@ -1,6 +1,9 @@
 <?php
 /**
- * PHP script to stream out an image thumbnail.
+ * The web entry point for retreiving media thumbnails.
+ *
+ * This script may also resize an image on-demand, if it isn't found in the
+ * configured FileBackend storage.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -19,6 +22,7 @@
  *
  * @file
  * @ingroup Media
+ * @ingroup entrypoint
  */
 
 use MediaWiki\Logger\LoggerFactory;

thumb_handler.php

@@ -1,7 +1,10 @@
 <?php
 /**
- * PHP script to be used as 404 handler to create and stream out a
- * not yet existing image thumbnail.
+ * The web entry point to be used as 404 handler behind a web server rewrite
+ * rule for media thumbnails. This script will interpret a request URL
+ * like `/w/images/thumb/a/a9/Example.jpg/50px-Example.jpg` and treat it as
+ * if it was a request to thumb.php with the relevant query parameters filled
+ * out. See also $wgGenerateThumbnailOnParse.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -20,6 +23,7 @@
  *
  * @file
  * @ingroup Media
+ * @ingroup entrypoint
  */
 
 define( 'THUMB_HANDLER', true );