Issue #2490782 by MegaChriz, donquixote: Added parameter types for a few...

Issue #2490782 by MegaChriz, donquixote: Added parameter types for a few docblocks and some other code style fixes.

includes/FeedsConfigurable.inc

@@ -22,10 +22,18 @@ class FeedsNotExistingException extends Exception {
  */
 abstract class FeedsConfigurable {
 
-  // Holds the actual configuration information.
+  /**
+   * Holds the actual configuration information.
+   *
+   * @var array
+   */
   protected $config;
 
-  // A unique identifier for the configuration.
+  /**
+   * A unique identifier for the configuration.
+   *
+   * @var string
+   */
   protected $id;
 
   /*
@@ -40,22 +48,36 @@ abstract class FeedsConfigurable {
   EXPORT_IN_CODE - the configurable is defined in code.
   EXPORT_IN_CODE | EXPORT_IN_DATABASE - the configurable is defined in code, but
   overridden in the database.*/
+
+  /**
+   * @var int
+   */
   protected $export_type;
 
   /**
    * CTools export enabled status of this object.
+   *
+   * @var bool
    */
   protected $disabled;
 
   /**
-   * Instantiates a FeedsConfigurable object.
+   * Provides a statically cached instance of a FeedsConfigurable subclass.
    *
    * Don't use directly, use feeds_importer() or feeds_plugin() instead.
    *
+   * @param string $class
+   *   The name of a subclass of FeedsConfigurable.
+   * @param string $id
+   *
+   * @return FeedsConfigurable
+   * @throws \Exception
+   *
    * @see feeds_importer()
    * @see feeds_plugin()
    */
   public static function instance($class, $id) {
+    // @todo Verify that $class is an existing subclass of FeedsConfigurable.
     if (!strlen($id)) {
       throw new InvalidArgumentException(t('Empty configuration identifier.'));
     }
@@ -70,6 +92,8 @@ abstract class FeedsConfigurable {
 
   /**
    * Constructor, set id and load default configuration.
+   *
+   * @param string $id
    */
   protected function __construct($id) {
     // Set this object's id.
@@ -84,6 +108,10 @@ abstract class FeedsConfigurable {
 
   /**
    * Override magic method __isset(). This is needed due to overriding __get().
+   *
+   * @param string $name
+   *
+   * @return bool
    */
   public function __isset($name) {
     return isset($this->$name) ? TRUE : FALSE;
@@ -114,6 +142,10 @@ abstract class FeedsConfigurable {
   /**
    * Determine whether this object is persistent and enabled. I. e. it is
    * defined either in code or in the database and it is enabled.
+   *
+   * @return $this
+   *
+   * @throws FeedsNotExistingException
    */
   public function existing() {
     if (!$this->doesExist()) {
@@ -133,6 +165,8 @@ abstract class FeedsConfigurable {
 
   /**
    * Copy a configuration.
+   *
+   * @param FeedsConfigurable $configurable
    */
   public function copy(FeedsConfigurable $configurable) {
     $this->setConfig($configurable->config);
@@ -141,7 +175,7 @@ abstract class FeedsConfigurable {
   /**
    * Set configuration.
    *
-   * @param $config
+   * @param array $config
    *   Array containing configuration information. Config array will be filtered
    *   by the keys returned by configDefaults() and populated with default
    *   values that are not included in $config.
@@ -154,7 +188,7 @@ abstract class FeedsConfigurable {
   /**
    * Similar to setConfig but adds to existing configuration.
    *
-   * @param $config
+   * @param array $config
    *   Array containing configuration information. Will be filtered by the keys
    *   returned by configDefaults().
    */
@@ -184,6 +218,8 @@ abstract class FeedsConfigurable {
    * Implements getConfig().
    *
    * Return configuration array, ensure that all default values are present.
+   *
+   * @return array
    */
   public function getConfig() {
     $defaults = $this->configDefaults();
@@ -228,7 +264,9 @@ abstract class FeedsConfigurable {
    * Return configuration form for this object. The keys of the configuration
    * form must match the keys of the array returned by configDefaults().
    *
-   * @return
+   * @param array $form_state
+   *
+   * @return array
    *   FormAPI style form definition.
    */
   public function configForm(&$form_state) {
@@ -249,7 +287,7 @@ abstract class FeedsConfigurable {
   /**
    * Submission handler for configForm().
    *
-   * @param $values
+   * @param array $values
    */
   public function configFormSubmit(&$values) {
     $this->addConfig($values);
@@ -274,12 +312,11 @@ abstract class FeedsConfigurable {
  * Config form wrapper. Use to render the configuration form of
  * a FeedsConfigurable object.
  *
- * @param $configurable
- *   FeedsConfigurable object.
- * @param $form_method
+ * @param FeedsConfigurable $configurable
+ * @param string $form_method
  *   The form method that should be rendered.
  *
- * @return
+ * @return array|null
  *   Config form array if available. NULL otherwise.
  */
 function feeds_get_form($configurable, $form_method) {
@@ -292,14 +329,15 @@ function feeds_get_form($configurable, $form_method) {
  * Config form callback. Don't call directly, but use
  * feeds_get_form($configurable, 'method') instead.
  *
- * @param
- *   FormAPI $form_state.
- * @param
- *   FeedsConfigurable object.
- * @param
+ * @param array $form
+ * @param array $form_state
+ * @param FeedsConfigurable $configurable
  *   The object to perform the save() operation on.
- * @param $form_method
+ * @param string $form_method
  *   The $form_method that should be rendered.
+ *
+ * @return array
+ *   Form array.
  */
 function feeds_form($form, &$form_state, $configurable, $form_method) {
   $form = $configurable->$form_method($form_state);
@@ -317,6 +355,9 @@ function feeds_form($form, &$form_state, $configurable, $form_method) {
 
 /**
  * Validation handler for feeds_form().
+ *
+ * @param array $form
+ * @param array $form_state
  */
 function feeds_form_validate($form, &$form_state) {
   _feeds_form_helper($form, $form_state, 'Validate');
@@ -324,6 +365,9 @@ function feeds_form_validate($form, &$form_state) {
 
 /**
  * Submit handler for feeds_form().
+ *
+ * @param array $form
+ * @param array $form_state
  */
 function feeds_form_submit($form, &$form_state) {
   _feeds_form_helper($form, $form_state, 'Submit');
@@ -333,6 +377,10 @@ function feeds_form_submit($form, &$form_state) {
  * Helper for Feeds validate and submit callbacks.
  *
  * @todo This is all terrible. Remove.
+ *
+ * @param array $form
+ * @param array $form_state
+ * @param string $action
  */
 function _feeds_form_helper($form, &$form_state, $action) {
   $method = $form['#feeds_form_method'] . $action;

includes/FeedsImporter.inc

@@ -27,14 +27,34 @@ class FeedsImporter extends FeedsConfigurable {
   // Every feed has a fetcher, a parser and a processor.
   // These variable names match the possible return values of
   // FeedsPlugin::typeOf().
-  protected $fetcher, $parser, $processor;
 
-  // This array defines the variable names of the plugins above.
+  /**
+   * @var FeedsFetcher|null
+   */
+  protected $fetcher;
+
+  /**
+   * @var FeedsParser|null
+   */
+  protected $parser;
+
+  /**
+   * @var FeedsProcessor|null
+   */
+  protected $processor;
+
+  /**
+   * This array defines the variable names of the plugins above.
+   *
+   * @var string[]
+   */
   protected $plugin_types = array('fetcher', 'parser', 'processor');
 
   /**
    * Instantiate class variables, initialize and configure
    * plugins.
+   *
+   * @param string $id
    */
   protected function __construct($id) {
     parent::__construct($id);
@@ -277,6 +297,10 @@ class FeedsImporter extends FeedsConfigurable {
 
   /**
    * Override parent::configForm().
+   *
+   * @param array $form_state
+   *
+   * @return array
    */
   public function configForm(&$form_state) {
     $config = $this->getConfig();
@@ -338,6 +362,8 @@ class FeedsImporter extends FeedsConfigurable {
 
   /**
    * Reschedule if import period changes.
+   *
+   * @param array $values
    */
   public function configFormSubmit(&$values) {
     if ($this->config['import_period'] != $values['import_period']) {
@@ -361,6 +387,10 @@ class FeedsImporter extends FeedsConfigurable {
 
 /**
  * Helper, see FeedsDataProcessor class.
+ *
+ * @param int $timestamp
+ *
+ * @return null|string
  */
 function feeds_format_expire($timestamp) {
   if ($timestamp == FEEDS_EXPIRE_NEVER) {

includes/FeedsSource.inc

@@ -177,11 +177,25 @@ class FeedsSource extends FeedsConfigurable {
   // standalone import form within Feeds or by other API users.
   protected $feed_nid;
 
-  // The FeedsImporter object that this source is expected to be used with.
+  /**
+   * The FeedsImporter object that this source is expected to be used with.
+   *
+   * @var FeedsImporter
+   */
   protected $importer;
 
-  // A FeedsSourceState object holding the current import/clearing state of this
-  // source.
+  /**
+   * A FeedsSourceState object holding the current import/clearing state of this
+   * source.
+   *
+   * Array keys are stages, such as FEEDS_START or FEEDS_PARSE.
+   * Array values can be FeedsState objects, or integer timestamps, or possibly
+   * something else.
+   *
+   * @todo Clarify the role of this variable.
+   *
+   * @var FeedsState[]|array|null
+   */
   protected $state;
 
   // Fetcher result, used to cache fetcher result when batching.
@@ -249,6 +263,8 @@ class FeedsSource extends FeedsConfigurable {
 
   /**
    * Returns the FeedsImporter object that this source is expected to be used with.
+   *
+   * @return FeedsImporter
    */
   public function importer() {
     return $this->importer;
@@ -257,10 +273,10 @@ class FeedsSource extends FeedsConfigurable {
   /**
    * Preview = fetch and parse a feed.
    *
-   * @return
+   * @return FeedsParserResult
    *   FeedsParserResult object.
    *
-   * @throws
+   * @throws Exception
    *   Throws Exception if an error occurs when fetching or parsing.
    */
   public function preview() {
@@ -665,8 +681,13 @@ class FeedsSource extends FeedsConfigurable {
    * @param $stage
    *   One of FEEDS_FETCH, FEEDS_PARSE, FEEDS_PROCESS or FEEDS_PROCESS_CLEAR.
    *
-   * @return
+   * @return FeedsState|mixed
    *   The FeedsState object for the given stage.
+   *   In theory, this could return something else, if $this->state has been
+   *   polluted with e.g. integer timestamps.
+   *
+   * @see FeedsSource::$state
+   * @todo Clarify the role of $this->state.
    */
   public function state($stage) {
     if (!is_array($this->state)) {
@@ -1008,7 +1029,7 @@ class FeedsSource extends FeedsConfigurable {
    * @param FeedsSourceInterface $client
    *   An object that is an implementer of FeedsSourceInterface.
    *
-   * @return
+   * @return array
    *   An array stored for $client.
    */
   public function getConfigFor(FeedsSourceInterface $client) {
@@ -1021,10 +1042,10 @@ class FeedsSource extends FeedsConfigurable {
    *
    * @param FeedsSourceInterface $client
    *   An object that is an implementer of FeedsSourceInterface.
-   * @param $config
+   * @param array $config
    *   The configuration for $client.
    *
-   * @return
+   * @return array
    *   An array stored for $client.
    */
   public function setConfigFor(FeedsSourceInterface $client, $config) {
@@ -1033,6 +1054,8 @@ class FeedsSource extends FeedsConfigurable {
 
   /**
    * Return defaults for feed configuration.
+   *
+   * @return array
    */
   public function configDefaults() {
     // Collect information from plugins.

plugins/FeedsProcessor.inc

@@ -641,7 +641,7 @@ abstract class FeedsProcessor extends FeedsPlugin {
    * @param FeedsSource $source
    *   The source to expire entities for.
    *
-   * @param $time
+   * @param int|null $time
    *   (optional) All items produced by this configuration that are older than
    *   REQUEST_TIME - $time should be deleted. If NULL, processor should use
    *   internal configuration. Defaults to NULL.
@@ -714,6 +714,8 @@ abstract class FeedsProcessor extends FeedsPlugin {
 
   /**
    * Counts the number of items imported by this processor.
+   *
+   * @return int
    */
   public function itemCount(FeedsSource $source) {
     return db_query("SELECT count(*) FROM {feeds_item} WHERE id = :id AND entity_type = :entity_type AND feed_nid = :feed_nid", array(':id' => $this->id, ':entity_type' => $this->entityType(), ':feed_nid' => $source->feed_nid))->fetchField();
@@ -886,6 +888,8 @@ abstract class FeedsProcessor extends FeedsPlugin {
   /**
    * Per default, don't support expiry. If processor supports expiry of imported
    * items, return the time after which items should be removed.
+   *
+   * @return int
    */
   public function expiryTime() {
     return FEEDS_EXPIRE_NEVER;
@@ -893,6 +897,8 @@ abstract class FeedsProcessor extends FeedsPlugin {
 
   /**
    * Declare default configuration.
+   *
+   * @return array
    */
   public function configDefaults() {
     $info = $this->entityInfo();
@@ -950,6 +956,10 @@ abstract class FeedsProcessor extends FeedsPlugin {
 
   /**
    * Overrides parent::configForm().
+   *
+   * @param array $form_state
+   *
+   * @return array
    */
   public function configForm(&$form_state) {
     $info = $this->entityInfo();
@@ -1058,6 +1068,8 @@ abstract class FeedsProcessor extends FeedsPlugin {
 
   /**
    * Get mappings.
+   *
+   * @return array
    */
   public function getMappings() {
     $cache = &drupal_static('FeedsProcessor::getMappings', array());
@@ -1099,7 +1111,7 @@ abstract class FeedsProcessor extends FeedsPlugin {
    *
    * @ingroup mappingapi
    *
-   * @return
+   * @return array
    *   An array of mapping targets. Keys are paths to targets
    *   separated by ->, values are TRUE if target can be unique,
    *   FALSE otherwise.