Contact: cleaned & added extra documentation

tripal_contact/api/tripal_contact.api.inc

@@ -1,4 +1,11 @@
 <?php
+/**
+ * @file
+ * Functions to interact with contacts.
+ *
+ * @ingroup tripal_contact
+ */
+
 /**
  * @defgroup tripal_contact_api Contact Module API
  * @ingroup tripal_api
@@ -68,6 +75,7 @@ function tripal_contact_insert_property($contact_id, $property, $value, $update_
 function tripal_contact_update_property($contact_id, $property, $value, $insert_if_missing = 0) {
   return tripal_core_update_property('contact', $contact_id, $property, 'tripal_contact', $value, $insert_if_missing);
 }
+
 /**
  * Delete a given property
  *
@@ -108,7 +116,6 @@ function tripal_contact_delete_property($contact_id, $property) {
  *   returned
  *
  * @ingroup tripal_contact_api
- *
  */
 function tripal_contact_add_contact($name, $description, $type, $properties) {
 
@@ -156,4 +163,4 @@ function tripal_contact_add_contact($name, $description, $type, $properties) {
     }
   }
   return $contact;
-}
+}

tripal_contact/includes/tripal_contact.admin.inc

@@ -1,7 +1,16 @@
 <?php
+/**
+ * @file
+ * Handle administration of contacts.
+ *
+ * @ingroup tripal_contact
+ */
 
 /**
+ * Launchpage for contact administration. Makes sure views are enabled and if not provides
+ * links to enable them.
  *
+ * @ingroup tripal_contact
  */
 function tripal_contact_admin_contact_view() {
   $output = '';
@@ -33,7 +42,6 @@ function tripal_contact_admin_contact_view() {
   return $output;
 }
 
-
 /**
  * Administrative settings form
  *
@@ -51,19 +59,20 @@ function tripal_contact_admin() {
 
 
 /**
+ * Reindex nodes for drupal search
  *
  * @ingroup tripal_contact
  */
 function get_tripal_contact_admin_form_reindex_set(&$form) {
 
- 
+
 }
+
 /**
+ * Validate the contact settings form.
  *
  * @ingroup tripal_contact
  */
 function tripal_contact_admin_validate($form, &$form_state) {
-  global $user;  // we need access to the user info
-  $job_args = array();
-}
 
+}

tripal_contact/includes/tripal_contact.chado_node.inc

@@ -1,9 +1,16 @@
 <?php
 /**
- * Implementation of hook_tripal_contact_node_info().
+ * @file
+ * Implements drupal node hooks.
  *
+ * @ingroup tripal_contact
+ */
+
+/**
+ * Implementation of hook_node_info().
  * This node_info, is a simple node that describes the functionallity of the module.
  *
+ * @ingroup tripal_contact
  */
 function tripal_contact_node_info() {
 
@@ -31,10 +38,9 @@ function tripal_contact_node_info() {
     ),
   );
 }
+
 /**
- * Implementation of tripal_contact_form().
- *
- *
+ * Implementation of hook_form().
  *
  *  @parm $node
  *    The node that is created when the database is initialized
@@ -46,6 +52,7 @@ function tripal_contact_node_info() {
  *  @return $form
  *    The information that was enterd allong with
  *
+ * @ingroup tripal_contact
  */
 function chado_contact_form(&$node, $form_state) {
   $form = array();
@@ -228,7 +235,8 @@ function chado_contact_form(&$node, $form_state) {
 }
 
 /**
- *  validates submission of form when adding or updating a contact node
+ * Implements hook_validate().
+ * Validates submission of form when adding or updating a contact node.
  *
  * @ingroup tripal_contact
  */
@@ -280,7 +288,7 @@ function chado_contact_validate($node, $form, &$form_state) {
 }
 
 /**
- * Implement hook_access().
+ * Implements hook_access().
  *
  * This hook allows node modules to limit access to the node types they define.
  *
@@ -300,6 +308,7 @@ function chado_contact_validate($node, $form, &$form_state) {
  *  access.  The only exception is when the $op == 'create'.  We will always
  *  return TRUE if the permission is set.
  *
+ * @ingroup tripal_contact
  */
 function chado_contact_node_access($node, $op, $account ) {
   if ($op == 'create') {
@@ -327,10 +336,8 @@ function chado_contact_node_access($node, $op, $account ) {
   return NULL;
 }
 
-
-
 /**
- * Implementation of tripal_contact_insert().
+ * Implements of hook_insert().
  *
  * This function inserts user entered information pertaining to the contact instance into the
  * 'contactauthor', 'contactprop', 'chado_contact', 'contact' talble of the database.
@@ -338,7 +345,7 @@ function chado_contact_node_access($node, $op, $account ) {
  *  @parm $node
  *    Then node which contains the information stored within the node-ID
  *
- *
+ * @ingroup tripal_contact
  */
 function chado_contact_insert($node) {
 
@@ -359,7 +366,7 @@ function chado_contact_insert($node) {
     $contact = tripal_core_chado_insert('contact', $values);
     if (!$contact) {
       drupal_set_message(t('Unable to add contact.', 'warning'));
-      tripal_core_report_error('tripal_contact', TRIPAL_ERROR, 
+      tripal_core_report_error('tripal_contact', TRIPAL_ERROR,
         'Insert contact: Unable to create contact where values: %values',
         array('%values' => print_r($values, TRUE)));
       return;
@@ -404,19 +411,18 @@ function chado_contact_insert($node) {
   return TRUE;
 }
 
-/*
+/**
+ * Implements hook_update
  *
-* Implements hook_update
-*
-* The purpose of the function is to allow the module to take action when an edited node is being
-* updated. It updates any name changes to the database tables that werec reated upon registering a contact.
-* As well, the database will be changed, so the user changed information will be saved to the database.
-*
-* @param $node
-*   The node being updated
-*
-* @ingroup tripal_contact
-*/
+ * The purpose of the function is to allow the module to take action when an edited node is being
+ * updated. It updates any name changes to the database tables that werec reated upon registering a contact.
+ * As well, the database will be changed, so the user changed information will be saved to the database.
+ *
+ * @param $node
+ *   The node being updated
+ *
+ * @ingroup tripal_contact
+ */
 function chado_contact_update($node) {
   // remove surrounding white-space on submitted values
   $node->contactname          = trim($node->contactname);
@@ -436,7 +442,7 @@ function chado_contact_update($node) {
   $status = tripal_core_chado_update('contact', $match, $values);
   if (!$status) {
     drupal_set_message("Error updating contact", "error");
-    tripal_core_report_error('tripal_contact', TRIPAL_ERROR, 
+    tripal_core_report_error('tripal_contact', TRIPAL_ERROR,
       "Error updating contact", array());
     return;
   }
@@ -464,10 +470,8 @@ function chado_contact_update($node) {
   chado_node_relationships_form_update_relationships($node, $details);
 }
 
-
 /**
- * Implementation of tripal_contact_load().
- *
+ * Implements hook_load().
  *
  * @param $node
  *   The node that is to be accessed from the database
@@ -475,6 +479,7 @@ function chado_contact_update($node) {
  * @return $node
  *   The node with the information to be loaded into the database
  *
+ * @ingroup tripal_contact
  */
 function chado_contact_load($nodes) {
 
@@ -510,7 +515,7 @@ function chado_contact_load($nodes) {
 }
 
 /**
- * Implementation of tripal_contact_delete().
+ * Implements hook_delete().
  *
  * This function takes a node and if the delete button has been chosen by the user, the contact
  * and it's details will be removed.Following,given the node-ID, the instance will be deleted from
@@ -519,6 +524,7 @@ function chado_contact_load($nodes) {
  *  @parm $node
  *    Then node which contains the information stored within the node-ID
  *
+ * @ingroup tripal_contact
  */
 function chado_contact_delete(&$node) {
 
@@ -544,10 +550,10 @@ function chado_contact_delete(&$node) {
   chado_query("DELETE FROM {contact} WHERE contact_id = :contact_id", array(':contact_id' => $contact_id));
 }
 
-
 /**
+ * Implements hook_node_view().
  *
- * @ingroup tripal_feature
+ * @ingroup tripal_contact
  */
 function tripal_contact_node_view($node, $view_mode, $langcode) {
   switch ($node->type) {
@@ -586,8 +592,9 @@ function tripal_contact_node_view($node, $view_mode, $langcode) {
 }
 
 /**
+ * Implements hook_node_presave().
  *
- * @param $node
+ * @ingroup tripal_contact
  */
 function tripal_contact_node_presave($node) {
   switch ($node->type) {
@@ -603,4 +610,4 @@ function tripal_contact_node_presave($node) {
       }
       break;
   }
-}
+}

tripal_contact/tripal_contact.install

@@ -2,16 +2,16 @@
 
 /**
  * @file
- * This file contains all the functions which describe and implement drupal database tables
- * needed by this module. This module was developed by Chad N.A. Krilow and Lacey-Anne Sanderson,
- * University of Saskatchewan.
+ * Handles install, uninstall, disable and enable functionality including database tables.
  *
- * The contact manamgenet module allows you to sync data in a chado/Tripal instance with
- * multiple contact/mysql instances as well as manage and create such contact instances
+ * @ingroup tripal_contact
  */
 
 /**
+ * Implements hook_disable().
  * Disable default views when module is disabled
+ *
+ * @ingroup tripal_contact
  */
 function tripal_contact_disable() {
 
@@ -27,6 +27,7 @@ function tripal_contact_disable() {
 /**
  * Implementation of hook_requirements().
  *
+ * @ingroup tripal_contact
  */
 function tripal_contact_requirements($phase) {
   $requirements = array();
@@ -45,6 +46,8 @@ function tripal_contact_requirements($phase) {
 
 /**
  * Implementation of hook_install().
+ *
+ * @ingroup tripal_contact
  */
 function tripal_contact_install() {
 
@@ -78,6 +81,8 @@ function tripal_contact_install() {
 
 /**
  * Implementation of hook_uninstall().
+ *
+ * @ingroup tripal_contact
  */
 function tripal_contact_uninstall() {
   /*
@@ -89,6 +94,11 @@ function tripal_contact_uninstall() {
     */
 }
 
+/**
+ * Adds any cvs needed by this module.
+ *
+ * @ingroup tripal_contact
+ */
 function tripal_contact_add_cvs() {
 
   tripal_cv_add_cv(
@@ -98,12 +108,19 @@ function tripal_contact_add_cvs() {
 
 }
 
+/**
+ * Adds any cvterms needed by this module.
+ *
+ * @ingroup tripal_contact
+ */
 function tripal_contact_add_cvterms() {
 
 }
 
 /**
  * Implementation of hook_schema().
+ *
+ * @ingroup tripal_contact
  */
 function tripal_contact_schema() {
   $schema['chado_contact'] = array(
@@ -138,9 +155,11 @@ function tripal_contact_schema() {
   return $schema;
 }
 
-
-/*
+/**
+ * Add any custom tables needed by this module.
+ * - Contactprop: keep track of properties of contact
  *
+ * @ingroup tripal_contact
  */
 function tripal_contact_add_custom_tables(){
   $schema = array (
@@ -206,9 +225,12 @@ function tripal_contact_add_custom_tables(){
 
 /**
  * This is the required update for tripal_contact when upgrading from Drupal core API 6.x.
+ *
+ * @ingroup tripal_contact
  */
 function tripal_contact_update_7000() {
 
   tripal_contact_add_cvs();
   tripal_contact_add_cvterms();
+
 }

tripal_contact/tripal_contact.module

@@ -1,4 +1,10 @@
 <?php
+/**
+ * @file
+ * Functions related to general module functionality.
+ *
+ * @ingroup tripal_contact
+ */
 
 /**
  * @defgroup tripal_contact Contact Module
@@ -8,44 +14,37 @@
  * @}
  */
 
-require('api/tripal_contact.api.inc');
-require('theme/tripal_contact.theme.inc');
-require('includes/tripal_contact.admin.inc');
-require('includes/tripal_contact.chado_node.inc');
+require 'api/tripal_contact.api.inc';
+
+require 'theme/tripal_contact.theme.inc';
+
+require 'includes/tripal_contact.admin.inc';
+require 'includes/tripal_contact.chado_node.inc';
 
 /**
- * Implements hook_views_api()
- * Purpose: Essentially this hook tells drupal that there is views support for
- *  for this module which then includes tripal_contact.views.inc where all the
- *  views integration code is
+ * Implements hook_views_api().
+ * Essentially this hook tells drupal that there is views support for
+ * for this module which then includes tripal_contact.views.inc where all the
+ * views integration code is.
  *
  * @ingroup tripal_contact
  */
 function tripal_contact_views_api() {
   return array(
-      'api' => 2.0,
+      'api' => 3.0,
   );
 }
 
 /**
- *
- * @ingroup tripal_contact
- */
-function tripal_contact_init() {
-
-}
-
-
-
-/**
- * Tripal-contact-Menu
- *
- * Implemets hook_menu(): Adds menu items for the tripal_contact module menu. This section
+ * Implemets hook_menu().
+ * Adds menu items for the tripal_contact module menu. This section
  * gives the outline for the main menu of the Tripal-contact module
  *
  * @return
  *   An array of menu items that is visible within the Drupal Menu, returned as soon
  *   as the program is ran
+ *
+ * @ingroup tripal_contact
  */
 function tripal_contact_menu() {
 
@@ -103,12 +102,13 @@ function tripal_contact_menu() {
 }
 
 /**
- * Implements hook_theme(): Register themeing functions for this module
- *
+ * Implements hook_theme().
+ * Register themeing functions for this module
  *
  * @return
  *   An array of themeing functions to register
  *
+ * @ingroup tripal_contact
  */
 function tripal_contact_theme($existing, $type, $theme, $path) {
   $core_path = drupal_get_path('module', 'tripal_core');
@@ -153,7 +153,10 @@ function tripal_contact_theme($existing, $type, $theme, $path) {
   );
   return $items;
 }
+
 /**
+ * Implements hook_block_info().
+ *
  * @ingroup tripal_contact
  */
 function tripal_contact_block_info() {
@@ -172,7 +175,9 @@ function tripal_contact_block_info() {
 
   return $blocks;
 }
+
 /**
+ * Implements hook_block_view().
  * @ingroup tripal_contact
  */
 function tripal_contact_block_view($delta = '') {
@@ -222,7 +227,9 @@ function tripal_contact_block_view($delta = '') {
 }
 
 /**
- * Implement hook_perm().
+ * Implement hook_permissions().
+ *
+ * @ingroup tripal_contact
  */
 function tripal_contact_permissions() {
   return array(
@@ -249,15 +256,10 @@ function tripal_contact_permissions() {
   );
 }
 
-
-
-
 /**
- * Implementation of hook_form_alter()
+ * Implementation of hook_form_alter().
  *
- * @param $form
- * @param $form_state
- * @param $form_id
+ * @ingroup tripal_contact
  */
 function tripal_contact_form_alter(&$form, &$form_state, $form_id) {
   // turn of preview button for insert/updates

tripal_contact/tripal_contact.views_default.inc

@@ -1,7 +1,15 @@
 <?php
+/**
+ * @file
+ * Define default views for contacts.
+ *
+ * @ingroup tripal_contact
+ */
 
 /**
+ * Implements hook_views_default_views().
  *
+ * @ingroup tripal_contact
  */
 function tripal_contact_views_default_views() {
   $views = array();
@@ -13,7 +21,9 @@ function tripal_contact_views_default_views() {
 }
 
 /**
+ * Define the default view for contact administration.
  *
+ * @ingroup tripal_contact
  */
 function tripal_contact_defaultview_admin_contacts() {
 
@@ -204,4 +214,4 @@ function tripal_contact_defaultview_admin_contacts() {
   $handler->display->display_options['filters']['type_id']['expose']['max_length'] = 40;
   */
   return $view;
-}
+}