The SVN system can be installed in several different ways. If you prefer a command line interface, you can install the SVN core system after downloading from the following URL:

http://subversion.tigris.org/

If you would prefer a GUI front end, you can use one of these implementations:

I recommend that you install TortoiseSVN if you're just getting started. It integrates perfectly with the Windows operating system and allows you to right-click on any file or folder to access the TortoiseSVN menu. Files can be updated and downloaded from the repository with a single click. You can download TortoiseSVN here:

http://tortoisesvn.tigris.org

The installation process is a simple three-step wizard. Once you install the application, you can right-click in any Explorer window. If you don't have any files or folders selected in an Explorer window, the first items in the File menu will provide access to all of the application functions.

Any SCC system needs a repository that acts like a vault to hold the current and archival copies of the files that have been registered with the application. For a single developer, a repository can simply be created as a folder on the local drive. Once the folder is created, SVN can be selected to register it as a repository, and it immediately creates the files and folders that will be needed by the application for housekeeping of the archive.

Create a folder and name it SVN_Repository. This folder may be located on your local drive or, for backup possibilities, may be located on a network drive that is scheduled for automated backup. If you would prefer to set up a SVN Server, you can easily find instructions on that process on the SVN site, although the configurations (particularly in regard to security) are beyond the scope of this book.

Right-click on the folder and, from the context menu, select the TortoiseSVN

Because SVN may be integrated with many development systems (most particularly, Eclipse), you will be able to use this repository from within your development environment.

Figure 6-1. When creating a new repository, leave the default selection for the repository type.

Eclipse is a professional development system originally created by IBM before it was transferred to the open source community. Eclipse has a complete IDE, and an extension gives the system full support for PHP development. The Eclipse IDE is project-based, so all of the various files of a project can be coordinated.

There is a plug-in for the Eclipse development system called Subclipse that seamlessly integrates SVN version control into the development environment. With a simple right-click and menu selection within the environment, you can check in or check out files for your project.

www.easyeclipse.org

Configuring Eclipse

When you first run Eclipse, the application will prompt you for the location of your workspace folder. Select the "Use this as the default" option so that workspace will be used in future executions.

The first time Eclipse opens, it will bring up the Welcome screen, as shown in Figure 6-2.

Figure 6-2. The Eclipse Welcome screen will take you through a brief tour of the interface and provides access to the complete tutorials.

Workbench Basics

In Eclipse, the development environment is called the workbench. The main workbench window appears as shown in Figure 6-3. The configuration of the workbench display is determined by the current perspective. A perspective governs which windows (or parts, as they are known in Eclipse terminology) are displayed and the current resources available. In the upper-right corner of the window, you can see the perspectives shortcut bar that allows switching between current perspectives, as well as opening other ones. The title bar shows which perspective is currently displayed. In this figure, the Resource perspective is being used.

You can create a new project from a variety of templates (such as Java, Static Web, PHP, XML, and so on), all of which include basic templates that cater to the type of project that is being created. The type you will be using for Joomla development will be a PHP project. Before you create a new project, it is useful for Joomla development that all project files have the security code that prevents the file from being executed outside of the Joomla framework.

To begin to familiarize yourself with Eclipse, modify the default PHP template to use the Joomla security code. Under the Window menu, select the Preferences option. The preferences are stored within a tree inside the window, as shown in Figure 6-4. Expand the PHPeclipse Web Development node, then expand the PHP node, and finally click on the Code Templates item.

Figure 6-3. The main workbench window contains the navigator, tasks, and outlines windows.

In the right pane of the Preferences window, you can see all of the available template files for this type of project. Select the "New PHP files" item and click the Edit button. You can now add any code you want to be presented in a new file. In this case, enter the following code:

// no direct access
defined('_JEXEC') or die('Restricted access'),

Click the OK button to save the changes. Now, any new PHP files created in Eclipse will automatically have run security included.

The Subclipse plug-in included with the EasyEclipse installation. If you have installed the standard Eclipse application, be sure to download and install Subclipse to give Eclipse access to the SVN functionality. Subclipse is available for download here:

http://subclipse.tigris.org

Figure 6-4. Preferences are organized under a tree structure.

Guestbook spamming is a common problem. Spammers use automated routines to locate guestbook features on Web sites and post spam links that lead to their sites. These serve two functions for the spammer: the generation of traffic if guestbook viewers click on the link and increased page ranking in the search engines because of the reference link.

This guestbook component protects against spammers by only letting registered users post to the guestbook, and using a regular expression to strip characters such as those that would allow active HTML (including links) to appear in the text of the entry.

However, if you intend to use this component to allow unregistered users to post entries, you should implement a CAPTCHA routine. The CAPTCHA will display a distorted series of numbers and letters within a graphic image and then ask the user to enter the characters into a text field for confirmation. Spam programs can't decipher the warped letters, so they are unable to post the spam.

Routines to generate a CAPTCHA (which stands for "Completely Automated Public Turing test to tell Computers and Humans Apart") image are freely available on the Web. Simply go to a search engine and enter CAPTCHA PHP. You will find many versions of example code. At the time of writing, one such free PHP routine is available at www.cryptographp.com.

Figure 6-5. Create a new PHP Project in Eclipse, and name it com_guestbook.

The front-end component is the display component. Since a component is a great deal more advanced than a module, a number of extensions (such as the Polls component) use a module to provide the front-end interface. However, modules can be limiting—especially if you want to allow interactive modification of data.

In the case of this guestbook component, the presentation will not only show all current entries, but below them will be a form to allow new entries, as shown in Figure 6-6. The front-end component will be accessible through a menu item.

Figure 6-6. The guestbook will show all of the entries and who they are from.

As you construct the code, you may notice that all variables that are accepted (either from query string parameters or variables posted by a user) are obtained through the getVar() method, rather than through traditional PHP calls. The getVar routine provides valuable security features by scrutinizing the values submitted by the user. Hacker submissions (such as a SQL injection attack) are automatically detected and removed. Be sure to use this routine to take advantage of some of the security built into the Joomla framework.

Creating the Front-End Component

Begin the coding for the project by creating the front-end component. This component will be displayed to registered users and will present all of the current guestbook entries. It will also allow the user to enter a new entry and submit it.

The component is broken into two functions: addEntry() and displayGuestbook(). The addEntry function is actually executed by the displayGuestbook function if the user enters form information and submits it. The displayGuestbook function queries the database and displays any entries it finds in the guestbook table. Following the entries, displayGuestbook includes a form that allows a user to make a new entry.

Note that the database query uses #__guestbook to reference the table name. Most likely, the table will be named jos_guestbook if the user has installed Joomla without changing the default prefix for tables. If the prefix has been changed, however, the database object will substitute the current prefix for the pound (#_) notation.

The guestbook table will not have been created the first time the component is displayed. Only after the first user posts an entry and the addEntry function is executed will the table exist on the server. Although the Create Table routine is executed each time against the MySQL server, if the table already exists on the server, the execution of the table creation command is aborted.

To create the component file, right-click in the Eclipse Navigator window on the project and select the New

<?php
/**
* @version $Id: guestbook.php 5203 2007-06-15 02:45:14Z DanR $
* @copyright Copyright (C) 2007 Dan Rahmel. All rights reserved.
* @package Guestbook
* This component displays guestbook entries and allows the addition
* of entries from registered users.
*/

// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

// Check the task parameter and execute appropriate function
switch( JRequest::getVar( 'task' )) {
    case 'add':
        addEntry();
        break;
    default:
        displayGuestbook();
        break;
}

// Process data received from form.
function addEntry()  {
     // Get reference to database object
     $db =& JFactory::getDBO();
     // Get user id for recording with entry.
     $user =& JFactory::getUser();
     $uid     = $user->get(id'),



     // Get message and location from form posting values
     $fldMessage = JRequest::getVar('message') ;
     // Strip away anything that could be code, carriage returns, and so on
     $fldMessage = preg_replace("/[^a-zA-Z0-9 .?!$()'"]/", "", $fldMessage);

// Escape the message so it can be placed in the insert statement
     $fldMessage = " ' " . $db->getEscaped($fldMessage) . " ' ";
     $fldLocation = " ' " . $db->getEscaped(JRequest::getVar( location' )) . " ' ";
     // Obtain userIP and store with entry for security reasons
     $userIp = " ' " . $_SERVER['REMOTE_ADDR'] . " ' ";

     $insertFields = "INSERT INTO #__guestbook " .
          "(message, created_by, location, userip) " .
          "VALUES (" . $fldMessage . "," . intval($uid) . "," .
               $fldLocation . "," . $userIp . ");";
     $db->setQuery( $insertFields, 0);
     $db->query();
     echo "<h1>Thanks for the entry!</h1>";
     echo "<a href=index.php?option=com_guestbook>" .
          "Return to guestbook</a>";
}

// Output a list of guestbook entries
function displayGuestbook() {
     $db =& JFactory::getDBO();
     // Query database and display guestbook entries
     $query = "SELECT a.message, u.name" .
     " FROM #__guestbook AS a" .
     " LEFT JOIN #__users AS u ON u.id=a.created_by" .
     " ORDER BY a.created DES"c;

     $db->setQuery( $query, 0);
     // Make sure rows were returned before outputting
     if($rows = $db->loadObjectList()) {
          foreach ($rows as $row)
          {
               // Encode text to HTML formatting
               $rowMessage = htmlspecialchars($row->message, ENT_QUOTES);
               echo "<b>" . $rowMessage . "</b>";
               echo " - " . $row->name;
               // Put horizontal rules between entries
               echo "<hr />";
          }
     }

// Display guestbook entry form
?>
<h1 class="contentheading">Guestbook Entry form</h1>

<form id="form1" name="form1" method="post"
     action="index.php?option=com_guestbook&task=add">
  <P>Enter message here:<br />
    <textarea name="message" cols="60" rows="4" id="message"></textarea>
  </P>
  <P>
    <label>Location (optional) : </label>
    <input name="location" type="text" id="location" />
  </P>
  <P>

<input type="submit" name="Submit" value="Post Entry" />
  </P>
</form>

<?php     } ?>

As soon as you've saved the file, Eclipse automatically evaluates the code contained in the file and updates the environment. For example, the Outline window on the right side of the workbench displays all functions or methods contained in the file, as shown in Figure 6-7. These outline entries act as hyperlinks, so if you click on one, the source code window will be immediately scrolled to that item. Click on the displayGuestbook() function. The editor window will highlight the function. Notice just to the left of the function header is a small circle with a minus (−) sign in it. If you click on the circle, the character will change to a plus (+) sign and the code will collapse as if it were the body of an outline. The ability to collapse code lines makes it convenient to manage large source files in Eclipse.

Click on the displayGuestbook() function. The editor window will highlight the function. Notice just to the left of the function header is a small circle with a minus (-) sign in it. If you click on the circle, the character will change to a plus (+) sign and the code will collapse as if it were the body of an outline. The ability to collapse code lines makes it convenient to manage large source files in Eclipse.

Figure 6-7. The method or functions of a file are displayed in the Outline window on the right side of the screen.

The Administrator portion of the component features three different execution paths. The displayEntries() function will create a display table of all the entries that exist in the guestbook table. Each entry in the table will include a link that can be used to edit that entry. Clicking on the link will recall the component, only this time with the task parameter of the query string is set to edit. That will cause the editEntry() function to execute and present a form with the values of the selected entry for modification. Once changes are complete and the administrator clicks the button to post the changes, the updateEntry() routine is executed to make the modifications to the table.

Create another new PHP File in the Eclipse interface, and name it admin.guestbook.php. This file will contain the administrative user interface for the component. Enter the following code:

<?php
/**
* @version $Id: guestbook.php 5203 2007-06-15 02:45:14Z DanR $
* @copyright Copyright (C) 2007 Dan Rahmel. All rights reserved.
* @package Guestbook
* This component displays guestbook entries and allows the addition
* of entries from registered users.
*/

// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

// Check the task parameter and execute appropriate function
switch( JRequest::getVar( 'task' )) {
    case 'edit':
        editEntry();
        break;
    case 'update':
        updateEntry();
        break;
    default:
        displayEntries();
        break;
}

// Record data received from form posting
function updateEntry()  {
     // Set title in Administrator interface
     JMenuBar::title( JText::_( 'Update Guestbook Entry' ), 'addedit.png' );

     // Get reference to database object
     $db =& JFactory::getDBO();

     // Retrieve data from form
     $fldMessage = " ' " . $db->getEscaped(JRequest::getVar('message')) . " ' ";
     $fldLocation = " ' " . $db->getEscaped(JRequest::getVar( 'location' )) . " ' ";
     $fldID = " ' " . $db->getEscaped(JRequest::getVar( 'id' )) . " ' ";

     // Record updates to jos_guestbook table
     $insertFields = "UPDATE #__guestbook " .

" SET message=" . $fldMessage . ", " .
          " location=" . $fldLocation .
          " WHERE id = " . $fldID ;
     $db->setQuery( $insertFields, 0);
     $db->query();
     echo "<h3>Field updated!</h3>";
     echo "<a href='index.php?option=com_guestbook'>Return to guestbook list</a>";
}

// Display edit list of all guestbook entries
function displayEntries() {
     // Set title in Administrator interface
     JMenuBar::title( JText::_( 'Guestbook Entries' ), 'addedit.png' );

     // Query database for guestbook entries
     $db =& JFactory::getDBO();
     $query = "SELECT a.id, a.message,a.created,a.created_by, u.name" .
     " FROM #__guestbook AS a" .
     " LEFT JOIN #__users AS u ON u.id=a.created_by" .
     " ORDER BY created DES"c;
     $db->setQuery( $query, 0, 10 );
     $rows = $db->loadObjectList();
?>
<table class="adminlist">
<tr>
     <td class="title" width=10%>
          <strong><?php echo JText::_( 'EntryID' ); ?></strong>
     </td>
     <td class="title" width=50%>
          <strong><?php echo JText::_( 'Entry' ); ?></strong>
     </td>
     <td class="title" width=10%>
          <strong><?php echo JText::_( 'Created' ); ?></strong>
     </td>
     <td class="title" width=10%>
          <strong><?php echo JText::_( 'Created by' ); ?></strong>
     </td>
</tr>

<?php
     foreach ($rows as $row) {
          $link = 'index.php?option=com_guestbook&task=edit&id='. $row->id;
          // Truncate row message for display
          $rowMessage = $row->message;
          if(strlen($rowMessage) > 100) {
               $rowMessage = substr($rowMessage, 0, 100) . "...";
          }
          echo "<tr>" .
               "<td>" . $row->id . "</td>" .
               "<td><a href=" . $link . ">" . $rowMessage . "</a></td>" .
               "<td>" . $row->created . "</td>" .
               "<td>" . $row->name . "</td>" .
               "</tr>";
     }

echo "</table>";
     echo "<h3>Click on an entry link in the table to edit entry.</h3>";
}

function editEntry() {
     JMenuBar::title( JText::_( 'Guestbook Entry Editor' ), 'addedit.png' );

     $db =& JFactory::getDBO();
     $query = "SELECT a.id, a.message,a.created,a.created_by,a.location" .
     " FROM #__guestbook AS a" .
     " WHERE a.id = " . JRequest::getVar( id' );
     $db->setQuery( $query, 0, 10 );
     If($rows = $db->loadObjectList()) {
?>

<form id="form1" name="form1" method="post"
action="index.php?option=com_guestbook&task=update">
  <P>Enter message here:<br />
    <textarea name="message" cols="60" rows="4" id="message"><?php
    echo $rows[0]->message;
    ?></textarea>
  </P>
  <P>
    <label>Location (optional) : </label>
    <input name="location" type="text" id="location"
    value='<?php echo $rows[0]->location; ?>'
    />
    <input name="id" type="hidden" id="id"
    value='<?php echo $rows[0]->id; ?>'
    />
  </P>
  <P>
    <input type="submit" name="Submit" value="Record Changes" />
  </P>
</form>

<?php }     } ?>

Save the file, and you will notice the same postprocessing will occur to file the Outline window.

The descriptor file for this component is more complicated than the simple one created for the Hello World component. This component has both front-end and Administrator files to install.

Since the Eclipse interface doesn't have a default new XML file selection, choose the File

<?xml version="1.0" encoding="utf-8"?>
<install version="1.5.0" type="component">
     <name>Guestbook</name>
     <author>Dan Rahmel</author>

<version>1.0.0</version>
     <description>Presents a guestbook and lists all of the current entries
     along with an entry form at the bottom for registered user
  additions.</description>
     <files>
          <filename component="com_guestbook">
               guestbook.php</filename>
     </files>
     <install>
          <sql>
               <file driver="mysql" charset="utf8">install.sql</file>
          </sql>
     </install>

     <uninstall>
          <sql>
               <file driver="mysql" charset="utf8">uninstall.sql</file>
          </sql>
     </uninstall>
     <administration>
          <menu>Guestbook</menu>
         <files>
              <filename component="admin.guestbook">
               admin.guestbook.php</filename>
               <filename>install.sql</filename>
               <filename>uninstall.sql</filename>
         </files>
     </administration>

</install>

When you save this file, the Outline window will update to show the entire XML schema, as shown in Figure 6-8. Clicking on any of the elements of the schema will highlight that element in the editor window. Eclipse understands the XML format, so if you right-click in the editor window, the context menu provides an option titled Validate. Selecting this option will validate the formatting of the XML and flag errors in the file with small red icons in the left margin.

This XML descriptor file is different from previous descriptors in that it references two SQL script files to create the guestbook table on install, and remove it when the component is uninstalled. You will need to create these two files that will be included in the package.

Create a new file called install.sql, and enter the following code:

CREATE TABLE IF NOT EXISTS '#__guestbook'
          ('id' INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
          'message' text NOT NULL, 'created_by' INTEGER UNSIGNED NOT NULL,
          'location' VARCHAR(45), 'created' TIMESTAMP NOT NULL,
          'userip' VARCHAR(16), PRIMARY KEY('id'))

Create another new file called uninstall.sql, and enter the following code:

DROP TABLE IF EXISTS '#__guestbook'

Figure 6-8. The XML schema of the file is displayed in the Outline window.

To add the project to the repository that you created earlier, right-click on the project and, from the context menu, select the Team

Select the "Create a new repository location" option, and click the Next button. You will be prompted for the URL of the location of the repository. As of this writing, there was no Browse button available, so you will have to enter the path by hand.

Once complete, your project will be archived in the repository. You can right-click on the individual files to store changes. You can also set a version tag when you have made comprehensive enough changes to warrant it.

Figure 6-9. Select the "Create a new repository location" to point Eclipse at your repository.

Your project is now ready for archiving and installing on the Joomla system. Eclipse can create the archive file for you! In the Navigator window, right-click on the com_guestbook project, and select the Export... option. The Export options window will be displayed, as shown in Figure 6-10. Expand the General category, select the Archive File option, and click the Next button.

The Archive file option box will display a number of different settings that can be used in creating the archive. In the file selection box, you should see your project checked in the left pane and all of the files selected in the right pane. Unless you want to deselect the project file for inclusion in the archive (it won't hurt anything if it is there), the default selections are fine.

Leave the default selections of "Save in zip format" and "Create directory structure for files." In the "To archive file" text box, enter or browse to a path on your local drive. Title the file com_guestbook.zip, and click the Finish button. Eclipse will create the archive file and store it on the local drive.

Figure 6-10. The Export options window provides the Archive selection to create a ZIP archive of all the project files.

Open the Extension Manager in the Joomla Administrator interface, and install the file. The archive created by Eclipse is properly formatted for the Joomla framework to place all the files into their proper locations. One file will be placed in the components folder, while the XML descriptor and the Administrator interface component will be placed in the administratorcomponents folder. In the future, you can edit them in these folders to support live development where testing code only requires a browser refresh.

When the Extension Manager informs you that the installation has succeeded, you should be able to see the Guestbook entry in the Components menu, as shown in Figure 6-11. You don't need to access it right now, since there are no guestbook entries to manage.

Create a menu item to the Guestbook control on the Main Menu. When the component list is presented for the new menu item, you should see the Guestbook item. Select Guestbook, and when the parameter screen is displayed, name the menu entry My Guestbook. For security reasons, be sure to set the menu so it will only be displayed to Registered users, as shown in Figure 6-12.

To try the guestbook, open a browser window and click on the My Guestbook link. There will be no entries, so only the entry form will be displayed. Enter a message in the guestbook as shown in Figure 6-13, and click the Post Entry button to send it into the system.

The guestbook will acknowledge your entry and provide a return link. Click the return link, and you should see the guestbook entries. With some entries in the jos_guestbook table, return to the Administrator interface. Select the Guestbook option from the Components menu. You'll see a row for each entry in the guestbook, as shown in Figure 6-14.

Figure 6-11. The Components menu will display the Guestbook entry that provides access to the guestbook administrative interface.

Figure 6-12. Restrict the users that may access the control to Registered users to prevent spammers from abusing the guestbook.

Figure 6-13. Enter a message in the guestbook form.

Each row of the table has the first 200 characters of the entry displayed as a link. Clicking on the link will take you to the edit form for that entry, as shown in Figure 6-15.

Any changes to the entry can be posted back into the database by clicking on the Record Changes button. For both security and convenience, nearly all characters beyond alphanumeric and basic punctuation are stripped from the entry when the user enters it through the front-end form. No such protection occurs through the Administrator interface form. It is possible that the Administrator will want to add any number of extras, so that functionality is left intact for those with administrative access.

The guestbook component has both a front-end and administrative interface, creates a custom table to store data, and accesses the data source for a variety of different activities (query, insert, and update). These features make it the perfect foundation from which you can build other database-centric components.

Figure 6-14. In the administrative interface, the guestbook will list all of the available entries.

Figure 6-15. Selecting a link from the table will display the editing form for that entry.

Installing phpDocumentor on your Web server is extremely easy. The program doesn't need any database access or rendering technology, so any Web server that can execute PHP code can use it.

First, you will need to download the archive of the latest version from SourceForge. You'll find the link at the phpDocumentor site here:

http://www.phpdoc.org

All you need to do is extract the files and folders into a folder on the Web server. Be sure that you don't locate it in a place that can be addressed by the public Internet, since it is not a secure application. On my staging server, I placed the files in a folder called phpdoc at the root of the Web server. To access the administrative interface, just enter a URL such as the following:

http://localhost/phpdoc

The Web interface displays a Welcome screen with a number of menus (Introduction, Config, Files, Output, and so on). It also displays the working directory and the current status of the application. Generally, the status will read "Awaiting your command."

You may have noticed that the source code in this book usually begins with a C++-style comment block that looks something like this:

/**
 *
 */

These comment sections are called DocBlocks and are harvested by phpDocumentor for inclusion in the code documentation. For complete documentation, one DocBlock should precede each element, including functions, classes, methods, and procedures.

The documentation is organized according to packages. A package is a conceptual grouping of classes, methods, and functions. You can explicitly define the package location of an element by using the @package tag. Within a master package, subpackages may also be defined with the @subpackage tag. Here is an example of some Joomla source code that is placed into the Joomla package and the Content subpackage:

/**
* @package Joomla
* @subpackage Content
*/
class TOOLBAR_content
{
     function _EDIT()
     {

To see how all of this works, you can execute phpDocumentor on Joomla itself, since it has the necessary DocBlocks to create basic documentation. Before you do, however, create a directory on your Web server to store the documentation files. The application generates numerous HTML files, so it's best to keep them centralized within a folder.

Open the phpDocumentor Web interface, and click on the Output tab link at the top of the page. The first field is labeled Target and specifies the directory where the parsed files will be written. Enter the directory path for the folder that you created a moment ago.

Click on the Files tab link to configure the files that will be parsed by the program. The includes directory of the Joomla system contains numerous classes that have DocBlocks. Enter a path to this folder, which, on the Windows platform, may look something like this:

C:Program FilesApache Software FoundationApache2.2htdocsincludes

To begin the process, click on the Create (new window) button. It may be a few minutes before the window is displayed, since Joomla has a great deal of code that must be processed. When complete, the status output of the documentation process will be presented. This window is very helpful when you have just begun using phpDocumentor because it will contain a list of errors or problems that occurred during the compilation.

Open the directory where the documentation was output, and open the index.html in a browser window. You will see a breakdown of the Joomla files contained in the includes directory. In the left column, there are links to each of the packages defined in the files, followed by a list of files documented, and, finally, the classes found within the packages.

In the classes section, click on the JSite link. You will see the class overview, as well as a list of methods for the class. The file contains class details (including comments from the development team), a breakdown of each class variable and method, and class constants.

Any development project can benefit greatly from having good programmer-level documentation. The few extra moments required to add this information to a file will reap significant rewards when later development is attempted. Be sure to read the phpDocumentor instructions because there are many other features such as the ability to include/exclude information for multiple versions of the documentation (one for developers and another for users, for example) and the functionality to include separate documentation files so source code can remain clean of extensive commentary.