- Patch by JonBob: for consistency and readability, add brief descriptions of each source file inside the @file comment block at the head of the file. This helps with Doxygen indexing, and also allows neophytes to see what a file does immediately on opening the source, regardless of the organization of the hooks.

cron.php

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Handles incoming requests to fire of regularly-scheduled tasks (cron jobs).
+ */
+
 include_once 'includes/bootstrap.inc';
 include_once 'includes/common.inc' ;
 

database/updates.inc

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * All incremental database updates performed between Drupal releases.
+ */
+
 // Define the various updates in an array("date : comment" => "function");
 $sql_updates = array(
   "2002-06-22: first update since Drupal 4.0.0 release" => "update_32",

includes/conf.php

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Drupal site-specific configuration file.
+ */
+
 #
 # Database settings:
 #

includes/file.inc

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * API for handling file uploads and server file management.
+ */
+
 /**
  * @defgroup file File interface
  *   Common file handling functions.

includes/locale.inc

@@ -1,10 +1,9 @@
 <?php
 // $Id$
+
 /**
  * @file
- *
+ * Admin-related functions for locale.module.
- * Admin related functions for locale.module
- *
  */
 
 // ---------------------------------------------------------------------------------

includes/session.inc

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * User session handling functions.
+ */
+
 session_set_save_handler("sess_open", "sess_close", "sess_read", "sess_write", "sess_destroy", "sess_gc");
 session_start();
 

index.php

@@ -1,6 +1,14 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * The PHP page that serves all page requests on a Drupal installation.
+ *
+ * The routines here dispatch control to the appropriate handler, which then
+ * prints the appropriate page.
+ */
+
 include_once 'includes/bootstrap.inc';
 drupal_page_header();
 include_once 'includes/common.inc';

modules/admin.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Handles the administration pages.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/aggregator.module

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * Used to aggregate syndicated content (RSS and RDF).
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/aggregator/aggregator.module

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * Used to aggregate syndicated content (RSS and RDF).
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/archive.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Displays a calendar to navigate old content.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/archive/archive.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Displays a calendar to navigate old content.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/block.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Controls the boxes that are displayed around the main content.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/block/block.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Controls the boxes that are displayed around the main content.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/blog.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables keeping an easily and regularly updated web page or a blog.
+ */
+
 /**
  * Implementation of hook_settings().
  */

modules/blog/blog.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables keeping an easily and regularly updated web page or a blog.
+ */
+
 /**
  * Implementation of hook_settings().
  */

modules/blogapi.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enable users to post using applications that support XML-RPC blog APIs.
+ */
+
 /**
  * Implementation of hook_help().
  */
@@ -9,7 +14,7 @@ function blogapi_help($section) {
     case 'admin/help#blogapi':
       return t('This module adds support for several XML-RPC based blogging APIs. Specifically, it currently implements the %bloggerAPI, %metaweblogAPI, and most of the %moveabletype extensions.  This allows users to contribute to drupal using external GUI applications, which can often offer richer functionality that online forms based editing', array('%bloggerAPI' => '<a href="http://www.blogger.com/developers/api/1_docs/">Blogger API</a>', '%metaweblogAPI' => '<a href="http://www.xmlrpc.com/metaWeblogApi">MetaWeblog API</a>', '%moveabletype' => '<a href="http://www.movabletype.org/docs/mtmanual_programmatic.html">Moveable Type API</a>'));
     case 'admin/modules#description':
-      return t('Enable users to post using applications that support XML-RPC blog APIs');
+      return t('Enable users to post using applications that support XML-RPC blog APIs.');
   }
 }
 

modules/blogapi/blogapi.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enable users to post using applications that support XML-RPC blog APIs.
+ */
+
 /**
  * Implementation of hook_help().
  */
@@ -9,7 +14,7 @@ function blogapi_help($section) {
     case 'admin/help#blogapi':
       return t('This module adds support for several XML-RPC based blogging APIs. Specifically, it currently implements the %bloggerAPI, %metaweblogAPI, and most of the %moveabletype extensions.  This allows users to contribute to drupal using external GUI applications, which can often offer richer functionality that online forms based editing', array('%bloggerAPI' => '<a href="http://www.blogger.com/developers/api/1_docs/">Blogger API</a>', '%metaweblogAPI' => '<a href="http://www.xmlrpc.com/metaWeblogApi">MetaWeblog API</a>', '%moveabletype' => '<a href="http://www.movabletype.org/docs/mtmanual_programmatic.html">Moveable Type API</a>'));
     case 'admin/modules#description':
-      return t('Enable users to post using applications that support XML-RPC blog APIs');
+      return t('Enable users to post using applications that support XML-RPC blog APIs.');
   }
 }
 

modules/book.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Allows users to collaboratively author a book.
+ */
+
 /**
  * Implementation of hook_node_name().
  */

modules/book/book.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Allows users to collaboratively author a book.
+ */
+
 /**
  * Implementation of hook_node_name().
  */

modules/comment.module

@@ -3,8 +3,7 @@
 
 /**
  * @file
- *
+ * Enables users to comment on published content.
- * Enables user to comment on published content.
  *
  * When enabled, the Drupal comment module creates a discussion
  * board for each Drupal node. Users can post comments to discuss

modules/comment/comment.module

@@ -3,8 +3,7 @@
 
 /**
  * @file
- *
+ * Enables users to comment on published content.
- * Enables user to comment on published content.
  *
  * When enabled, the Drupal comment module creates a discussion
  * board for each Drupal node. Users can post comments to discuss

modules/drupal.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Lets users log in using a Drupal ID and can notify a central server about your site.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/drupal/drupal.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Lets users log in using a Drupal ID and can notify a central server about your site.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/filter.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Framework for handling filtering of content.
+ */
+
 define('FILTER_FORMAT_DEFAULT', 0);
 
 define('FILTER_HTML_STRIP', 1);

modules/filter/filter.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Framework for handling filtering of content.
+ */
+
 define('FILTER_FORMAT_DEFAULT', 0);
 
 define('FILTER_HTML_STRIP', 1);

modules/forum.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enable threaded discussions about general topics.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/forum/forum.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enable threaded discussions about general topics.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/help.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Manages displaying online help.
+ */
+
 /**
  * Implementation of hook_menu().
  */

modules/help/help.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Manages displaying online help.
+ */
+
 /**
  * Implementation of hook_menu().
  */

modules/locale.module

@@ -3,7 +3,6 @@
 
 /**
  * @file
- *
  * Enables administrators to manage the site interface languages.
  *
  * When enabled, the site interface can be displayed in different

modules/locale/locale.module

@@ -3,7 +3,6 @@
 
 /**
  * @file
- *
  * Enables administrators to manage the site interface languages.
  *
  * When enabled, the site interface can be displayed in different

modules/menu.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Allows administrators to customize the site navigation menu.
+ */
+
 /**
  * Implementation of hook_menu().
  */

modules/menu/menu.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Allows administrators to customize the site navigation menu.
+ */
+
 /**
  * Implementation of hook_menu().
  */

modules/node.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * The core that allows content to be submitted to the site.
+ */
+
 define('NODE_NEW_LIMIT', time() - 30 * 24 * 60 * 60);
 
 /**

modules/node/node.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * The core that allows content to be submitted to the site.
+ */
+
 define('NODE_NEW_LIMIT', time() - 30 * 24 * 60 * 60);
 
 /**

modules/page.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables the creation of pages that can be added to the navigation system.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/page/page.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables the creation of pages that can be added to the navigation system.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/path.module

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * Enables users to rename URLs.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/path/path.module

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * Enables users to rename URLs.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/ping.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Alerts other sites that your site has been updated.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/ping/ping.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Alerts other sites that your site has been updated.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/poll.module

@@ -1,6 +1,12 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables your site to capture votes on different topics in the form of multiple
+ * choice questions.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/poll/poll.module

@@ -1,6 +1,12 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables your site to capture votes on different topics in the form of multiple
+ * choice questions.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/profile.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Support for configurable user profiles.
+ */
+
 /**
  * Flags to define the visibility of a profile field.
  */

modules/profile/profile.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Support for configurable user profiles.
+ */
+
 /**
  * Flags to define the visibility of a profile field.
  */

modules/queue.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables content to be moderated by the community.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/search.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables site-wide keyword searching.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/search/search.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables site-wide keyword searching.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/statistics.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Logs access statistics for your site.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/statistics/statistics.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Logs access statistics for your site.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/story.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables users to submit stories, articles or similar content.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/story/story.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables users to submit stories, articles or similar content.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/system.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Configuration system that lets administrators modify the workings of the site.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/system/system.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Configuration system that lets administrators modify the workings of the site.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/taxonomy.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables the organization of content into categories.
+ */
+
 /**
  * Implementation of hook_perm().
  */

modules/taxonomy/taxonomy.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables the organization of content into categories.
+ */
+
 /**
  * Implementation of hook_perm().
  */

modules/throttle.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Allows configuration of congestion control auto-throttle mechanism.
+ */
+
 /**
  * Determine the current load on the site.
  *

modules/throttle/throttle.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Allows configuration of congestion control auto-throttle mechanism.
+ */
+
 /**
  * Determine the current load on the site.
  *

modules/tracker.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables tracking of recent posts for users.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/tracker/tracker.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables tracking of recent posts for users.
+ */
+
 /**
  * Implementation of hook_help().
  */

modules/upload.module

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * File-handling and attaching files to nodes.
+ */
+
 function upload_help($section) {
   switch ($section) {
     case 'admin/modules#description':

modules/upload/upload.module

@@ -1,6 +1,11 @@
 <?php
 /* $Id$ */
 
+/**
+ * @file
+ * File-handling and attaching files to nodes.
+ */
+
 function upload_help($section) {
   switch ($section) {
     case 'admin/modules#description':

modules/user.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables the user registration and login system.
+ */
+
 /**
  * Invokes hook_user() in every module.
  *

modules/user/user.module

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Enables the user registration and login system.
+ */
+
 /**
  * Invokes hook_user() in every module.
  *

modules/watchdog.module

@@ -3,7 +3,6 @@
 
 /**
  * @file
- *
  * System monitoring and logging for administrators.
  *
  * The watchdog module monitors your site and keeps a list of

modules/watchdog/watchdog.module

@@ -3,7 +3,6 @@
 
 /**
  * @file
- *
  * System monitoring and logging for administrators.
  *
  * The watchdog module monitors your site and keeps a list of

themes/chameleon/chameleon.theme

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * A slim, CSS-driven theme.
+ */
+
 function chameleon_features() {
   return array(
        'logo',

themes/engines/xtemplate/xtemplate.engine

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Handles the interface between XTemplate files and the Drupal theme system.
+ */
+
 // Initialize the xtemplate engine.
 function xtemplate_init($template) {
   // We cannot use the theme() or path_to_theme() functions here

update.php

@@ -1,19 +1,21 @@
 <?php
 // $Id$
-/*
+
-** USAGE:
+/**
-**
+ * @file
-** - Point your browser to "http://www.site.com/update.php" and follow
+ * Administrative page for handling updates from one Drupal version to another.
-**   the instructions.
+ *
-**
+ * Point your browser to "http://www.site.com/update.php" and follow the
-** - If you are not logged in as administrator, you will need to modify the
+ * instructions.
-**   statement below. Change the 1 into a 0 to disable the access check.
+ *
-**   After finishing the upgrade, open this file and change the 0 back into
+ * If you are not logged in as administrator, you will need to modify the access
-**   a 1!
+ * check statement below. Change the TRUE into a FALSE to disable the access
+ * check. After finishing the upgrade, be sure to open this file and change the
+ * FALSE back into a TRUE!
  */
 
 // Disable access checking?
-$access_check = 1;
+$access_check = TRUE;
 
 if (!ini_get("safe_mode")) {
   set_time_limit(180);

xmlrpc.php

@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * PHP page for handling incoming XML-RPC requests from clients.
+ */
+
 include_once 'includes/bootstrap.inc';
 include_once 'includes/common.inc';
 include_once 'includes/xmlrpc.inc';