Index: inline.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/inline/inline.module,v
retrieving revision 1.26
diff -u -r1.26 inline.module
--- inline.module	18 Apr 2007 11:21:56 -0000	1.26
+++ inline.module	26 Apr 2007 13:11:26 -0000
@@ -21,10 +21,16 @@
   return $items;
 }
 
+/**
+ * Implementation of hook_perm().
+ */
 function inline_perm() {
   return array('administer inline settings');
 }
 
+/**
+ * Implementation of hook_help().
+ */
 function inline_help($section = 'admin/help#inline') {
   $output = '';
   switch ($section) {
@@ -40,6 +46,9 @@
   }
 }
 
+/**
+ * Inline settings form builder function.
+ */
 function inline_settings() {
   $form = array();
   
@@ -80,6 +89,8 @@
     '#description' => (module_exists('imagecache') ? t('Select the <a href="!presets">Imagecache presets</a> to use for inlined images.', array('!presets' => url('admin/settings/imagecache'))) : t('<strong>Note:</strong> If <a href="!imagecache">Imagecache</a> module is installed, Inline provides support for image scaling.', array('!imagecache' => url('http://drupal.org/project/imagecache')))),
   );
   
+  // If Imagecache module exists and is enabled, we assume that we want to use
+  // the improved image handling instead of our own.
   if (module_exists('imagecache')) {
     $options     = array();
     $options[''] = 'No Imagecache processing';
@@ -117,6 +128,11 @@
   return system_settings_form($form);
 }
 
+/**
+ * Implementation of hook_form_alter().
+ * 
+ * Allows to enable/disable auto-inline support for each content type.
+ */
 function inline_form_alter($form_id, &$form) {
   if ($form_id == 'node_type_form') {
     $node_type = $form['orig_type']['#value'];
@@ -130,6 +146,14 @@
   }
 }
 
+/**
+ * Implementation of hook_filter().
+ * 
+ * Since Inline needs to know which files are attached to a processed node, the 
+ * original text is simply returned here.
+ * 
+ * @see inline_nodeapi().
+ */
 function inline_filter($op, $delta = 0, $format = -1, $text = '') {
   if ($op == 'list') {
     return array(0 => t('Inline file filter'));
@@ -147,6 +171,9 @@
   }
 }
 
+/**
+ * Implementation of hook_filter_tips().
+ */
 function inline_filter_tips($delta, $format, $long = false) {
   if ($long) {
     return t('
@@ -174,6 +201,16 @@
   }
 }
 
+/**
+ * Implementation of hook_nodeapi().
+ * 
+ * Substitutes Inline tags with the corresponding files or images in front of
+ * node_view().
+ * Replaces numeric file references in Inline tags (i.e. [inline:1]) with named
+ * file references (i.e. [inline:foo.jpg]) upon node preview and node save.
+ * 
+ * @todo Break processing at all if Inline filter is not enabled.
+ */
 function inline_nodeapi(&$node, $op, $arg) {
   if (!is_array($node->files)) {
     return;
@@ -181,7 +218,7 @@
   switch ($op) {
     case 'alter':
     case 'print':
-      // only nodes with our inline filter in the format may be altered
+      // Only nodes with Inline filter in the format may be processed.
       foreach (filter_list_format($node->format) as $filter) {
         if ($filter->module == 'inline') {
           $node->teaser = _inline_substitute_tags($node, 'teaser');
@@ -202,8 +239,12 @@
   }
 }
 
+/**
+ * Return the corresponding file object of an Inline tag.
+ */
 function _inline_fileobj(&$node, $id) {
   if (is_numeric($id)) {
+    // Numeric file reference (deprecated, see #38359).
     $n = 1;
     foreach ($node->files as $file) {
       if ($n == $id) {
@@ -214,6 +255,7 @@
     return NULL;
   }
   else {
+    // Named file reference.
     foreach ($node->files as $file) {
       $file = (object)$file;
       if ($file->filename == $id) {
@@ -225,7 +267,13 @@
 }
 
 /**
- * Prepares the file object
+ * Change file path of new files for previews.
+ * 
+ * New files are stored in a temporary upload directory until the content
+ * is saved. We alter the file object accordingly, so such files may be
+ * displayed if the temporary directory is publicly accessible.
+ * 
+ * @todo Prepend 'system/' for private files support.
  */
 function inline_prepare_file_object($file) {
   $file = (object)$file;
@@ -238,14 +286,21 @@
   return $file;
 }
 
+/**
+ * Return HTML for a link to a file.
+ */
 function theme_inline_as_link($file) {
-  // prepare link text with title or filename
+  // Prepare link text with title or filename.
   $linktext = ($file->title ? $file->title : $file->filename);
   
   return l($linktext, file_create_url($file->filepath), array('title' => t('Download: @name (@size)', array('@name' => $file->filename, '@size' => format_size($file->filesize)))));
 }
 
+/**
+ * Return HTML for an image.
+ */
 function theme_inline_img($file, $field) {
+  // Prepare link text with title or filename.
   $title = (!empty($file->title) ? $file->title : $file->filename);
   $inline_preset = $field == 'teaser' ? 'inline_teaser_preset' : 'inline_full_preset';
   
@@ -281,21 +336,43 @@
   return $html;
 }
 
+/**
+ * Insert an image in front of node teaser.
+ * 
+ * @param object $node
+ *   The node object to process.
+ * @param object $file
+ *   A file object of an image to insert.
+ * @param string $field
+ *   The field name to prepend with the image.
+ */
 function theme_inline_add_to_teaser($node, $file, $field) {
   return theme('inline_img', $file, $field) . $node->teaser;
 }
 
+/**
+ * Insert an image in front of node body.
+ * 
+ * @param object $node
+ *   The node object to process.
+ * @param object $file
+ *   A file object of an image to insert.
+ * @param string $field
+ *   The field name to prepend with the image.
+ */
 function theme_inline_add_to_body($node, $file, $field) {
   return theme('inline_img', $file, $field) . $node->body;
 }
 
+/**
+ * Automatically add all images to configured node views.
+ * 
+ * This feature can be configured per content-type.
+ */
 function _inline_auto_add($node) {
-  //0 Disabled
-  //1 Only in teaser
-  //2 Only in body
-  //3 In teaser and body
   switch (variable_get('upload_inline_'. $node->type, 0)) {
     case 1:
+      // Display only in teaser.
       foreach ($node->files as $fid => $file) {
         $file = inline_prepare_file_object($file);
         if (_inline_decide_img_tag($file)) {
@@ -309,6 +386,7 @@
       break;
     
     case 2:
+      // Display only in body.
       foreach ($node->files as $fid => $file) {
         $file = inline_prepare_file_object($file);
         if (_inline_decide_img_tag($file)) {
@@ -322,6 +400,7 @@
       break;
     
     case 3:
+      // Display in teaser and body.
       foreach ($node->files as $fid => $file) {
         $file = inline_prepare_file_object($file);
         if (_inline_decide_img_tag($file)) {
@@ -338,19 +417,30 @@
   return $node;
 }
 
+/**
+ * Replace all Inline tags with their corresponding files or images.
+ * 
+ * @param object $node
+ *   The node to process.
+ * @param string $field
+ *   The node field to process.
+ * 
+ * @return string
+ *   The processed content of the given node field.
+ */
 function _inline_substitute_tags(&$node, $field) {
   if (preg_match_all("/\[(inline|file|attachment):([^=\\]]+)=?([^\\]]*)?\]/i", $node->$field, $match)) {
+    $s = $r = array();
     foreach ($match[2] as $key => $value) {
-      // fetch file object
+      // Ensure that we deal with a file object.
       $file = inline_prepare_file_object(_inline_fileobj($node, $value));
-      // deal file title
-      $title = $match[3][$key];
-      if (!empty($title)) {
-        $file->title = $title;
-      }
-      $replace = "";
       if ($file->fid != NULL) {
-        //decide if we should show a link or an img tag
+        // Set user defined file title if given.
+        $title = $match[3][$key];
+        if (!empty($title)) {
+          $file->title = $title;
+        }
+        // Decide whether to show a link or an image tag.
         if (_inline_decide_img_tag($file)) {
           $replace = theme('inline_img', $file, $field);
         }
@@ -359,23 +449,27 @@
         }
       }
       else {
-        $replace = "<span style=\"color:red; font-weight:bold\">NOT FOUND: $value</span>";
+        $replace = '<span style="color: red; font-weight: bold;">NOT FOUND: '. $value .'</span>';
       }
-      $mtch[] = $match[0][$key];
-      $repl[] = $replace;
+      $s[] = $match[0][$key];
+      $r[] = $replace;
     }
-    return str_replace($mtch, $repl, $node->$field);
+    // Perform the replacements and return processed field.
+    return str_replace($s, $r, $node->$field);
   }
   return $node->$field;
 }
 
 /**
- * Replaces numeric file references with their respective file names.
+ * Replaces numeric file references with their corresponding file names.
  *
- * @param &$node The node object to process.
- * @param $field Field of node to process.
+ * @param object $node
+ *   The node object to process.
+ * @param string $field
+ *   A field name of the node to process.
  *
- * @return Processed $field of $node.
+ * @return
+ *   The processed content of the given node field.
  */
 function _inline_replace_numbers($node, $field) {
   $tag = '/\[(inline|file|attachment):(\d+?)(=.+?)?\]/i';
@@ -383,21 +477,21 @@
   preg_match_all($tag, $node->$field, $matches, PREG_SET_ORDER);
   if (!empty($matches)) {
     foreach ($matches as $match) {
-      // Attachment array key is the file ID.
+      // The array key of the attachment is the file ID (fid).
       $filekeys = array_keys($node->files);
-      $key = $filekeys[$match[2] - 1];
-      // If a corresponding file does exist, perform the replacement.
       // Because a user starts counting files from 1, we substract 1 here.
+      $key = $filekeys[$match[2] - 1];
+      // If user entered a non-existent number, continue with next tag.
       if (!isset($node->files[$key])) {
-        // If user entered a non-existent number, continue with next tag.
         continue;
       }
+      // If a corresponding file does exist, perform the replacement.
       if (is_array($node->files[$key])) {
-        // Node form submit
+        // Node form submit is an array.
         $filename = $node->files[$key]['filename'];
       }
       else {
-        // Node form prepare
+        // Node form prepare is an object.
         $filename = $node->files[$key]->filename;
       }
       $node->$field = str_replace($match[0], '['. $match[1] .':'. $filename . $match[3] .']', $node->$field);
@@ -407,11 +501,13 @@
 }
 
 /**
- * Decides if a tag (&lt;img&gt;) or a link to a file should be rendered
+ * Decide if an image tag (&lt;IMG&gt;) or a link to a file should be rendered.
  *
- * @param $file a file object
+ * @param $file
+ *   A file object.
  *
- * @return TRUE in case an img tag should be generated
+ * @return
+ *   TRUE in case an image tag should be generated.
  */
 function _inline_decide_img_tag($file) {
   $inlined = array('jpg', 'jpeg', 'pjpeg', 'gif', 'png');
@@ -421,7 +517,7 @@
       return TRUE;
     }
     else {
-      // read settings
+      // Read maximum dimension settings.
       list($maxwidth, $maxheight) = explode(',', variable_get('inline_img_dim', '150,150'));
       
       if ($file->preview) {