Improved comments.

library/Nagiostatus/Parser.php

@@ -141,11 +141,14 @@ public function buildDocument(Nagiostatus_Plugin_Abstract $plugin)
      *
      * @param string $pluginName
      *   The name of the plugin used to render the data, i.e. "xml" or "json".
+     *   Defaults to null meaning the default plugin is used.
      * @param bool $return
      *   Return the variable representation instead of outputing it.
      *
      * @return string|bool
-     *   The rendered status data, false if there are errors.
+     *   Returns false on errors. If $return is false, this method returns true
+     *   on success. If $return is true, this method returns the parsed document
+     *   as a string in the machine readable format determined by the plugin.
      */
     public function render($pluginName = null, $return = false)
     {

library/Nagiostatus/Plugin/Abstract.php

@@ -16,35 +16,37 @@
 /**
  * Base class for Nagiostatus plugins.
  *
+ * Plugins render the status.dat file in machine readable formats and output the
+ * data directly to STDOUT as opposed to building the document in memory.
+ *
  * @package    Nagiostatus
  * @subpackage Plugin
  */
 abstract class Nagiostatus_Plugin_Abstract
 {
-
     /**
-     * The Nagiostatus_Parser instance containing the parsed data.
+     * The calling Nagiostatus_Parser instance.
      *
      * @var Nagiostatus
      */
     protected $_parser;
 
     /**
-     * Sets the Nagiostatus_Parser instance containing the parsed data.
+     * Sets the calling Nagiostatus_Parser instance.
      *
      * @param Nagiostatus_Parser $status
-     *   The Nagiostatus_Parser instance containing the parsed data.
+     *   The calling Nagiostatus_Parser instance.
      */
     public function __construct(Nagiostatus_Parser $parser)
     {
         $this->_parser = $parser;
     }
 
     /**
-     * Returns the Nagiostatus_Parser instance containing the parsed data
+     * Returns the calling Nagiostatus_Parser instance.
      *
      * @return Nagiostatus_Parser
-     *   The Nagiostatus_Parser instance containing the parsed data
+     *   The calling Nagiostatus_Parser instance.
      */
     public function getParser()
     {
@@ -63,7 +65,7 @@ public function initDocument()
      * Outputs the status data in machine readable format.
      *
      * @param array $status
-     *   The parsed status information.
+     *   An individual status information block parsed as an associative array.
      */
     abstract public function execute(array $status);
 

library/Nagiostatus/Plugin/Json.php

@@ -22,7 +22,7 @@
 class Nagiostatus_Plugin_Json extends Nagiostatus_Plugin_Abstract
 {
     /**
-     * Whether the
+     * Flags whether we are parsing the first status block.
      *
      * @var boolean
      */