[3.1.0] Improve maintenance script documentation

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@1644 48356398-32a2-884e-a903-53898d9a118a

maintenance/flush-definition-cache.php

@@ -6,7 +6,12 @@ require_once 'common.php';
 assertCli();
 
 /**
- * Flushes the default HTMLDefinition serial cache
+ * @file
+ * Flushes the definition serial cache. This file should be
+ * called if changes to any subclasses of HTMLPurifier_Definition
+ * or related classes (such as HTMLPurifier_HTMLModule) are made. This
+ * may also be necessary if you've modified a customized version.
+ * 
  * @param Accepts one argument, cache type to flush; otherwise flushes all
  *      the caches.
  */

maintenance/generate-entity-file.php

@@ -8,7 +8,9 @@ assertCli();
 /**
  * @file
  * Parses *.ent files into an entity lookup table, and then serializes and
- * writes the whole kaboodle to a file. The resulting file should be versioned.
+ * writes the whole kaboodle to a file. The resulting file is cached so
+ * that this script does not need to be run. This script should rarely,
+ * if ever, be run, since HTML's entities are fairly immutable.
  */
 
 // here's where the entity files are located, assuming working directory

maintenance/generate-includes.php

@@ -10,6 +10,8 @@ assertCli();
 /**
  * @file
  * Generates an include stub for users who do not want to use the autoloader.
+ * When new files are added to HTML Purifier's main codebase, this file should
+ * be called.
  */
 
 chdir(dirname(__FILE__) . '/../library/');

maintenance/generate-ph5p-patch.php

@@ -1,5 +1,12 @@
 <?php
 
+/**
+ * @file
+ * This file compares our version of PH5P with Jero's original version, and
+ * generates a patch of the differences. This script should be run whenever
+ * library/HTMLPurifier/Lexer/PH5P.php is modified.
+ */
+
 $orig = realpath(dirname(__FILE__) . '/PH5P.php');
 $new  = realpath(dirname(__FILE__) . '/../library/HTMLPurifier/Lexer/PH5P.php');
 $newt = dirname(__FILE__) . '/PH5P.new.php'; // temporary file

maintenance/generate-schema-cache.php

@@ -9,7 +9,11 @@ assertCli();
 /**
  * @file
  * Generates a schema cache file from the contents of
- * library/HTMLPurifier/ConfigSchema/schema.ser
+ * library/HTMLPurifier/ConfigSchema/schema.ser.
+ * 
+ * This should be run when new configuration options are added to
+ * HTML Purifier. A cached version is available via SVN so this does not
+ * normally have to be regenerated.
  */
 
 $target = '../library/HTMLPurifier/ConfigSchema/schema.ser';

maintenance/generate-standalone.php

@@ -6,8 +6,10 @@ require_once 'common.php';
 assertCli();
 
 /**
+ * @file
  * Compiles all of HTML Purifier's library files into one big file
- * named HTMLPurifier.standalone.php.
+ * named HTMLPurifier.standalone.php. This is usually called during the
+ * release process.
  */
 
 /**