From 56b816a2984c350c35caa5b292bdbbcec8b6cdf8 Mon Sep 17 00:00:00 2001
From: Nigel Banks <nigel.g.banks@gmail.com>
Date: Mon, 26 Nov 2012 16:54:55 +0000
Subject: [PATCH] Fixed documentation errors

---
 includes/ingest.form.inc | 23 ++++++++++++++---------
 islandora.module         | 18 +++++++++---------
 2 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/includes/ingest.form.inc b/includes/ingest.form.inc
index d6381436..77717257 100644
--- a/includes/ingest.form.inc
+++ b/includes/ingest.form.inc
@@ -249,39 +249,44 @@ function islandora_ingest_form_submit(array $form, array &$form_state) {
 }
 
 /**
- * Gets the configuration.
+ * Gets the configuration used to create the multi-page ingest form.
  *
  * @param array $form_state
  *   The drupal form state.
  *
- * @return int
- *   The current step index.
+ * @return array
+ *   The configuration used to generate the multi-page ingest forms.
  */
 function islandora_ingest_form_get_configuration(array $form_state) {
   return $form_state['islandora']['configuration'];
 }
 
 /**
- * Gets the stored objects.
+ * Gets a reference to the stored NewFedoraObject's which are to be ingested when the final step submits.
  *
  * @param array $form_state
  *   The drupal form state.
  *
- * @return int
- *   The current step index.
+ * @return array
+ *   A reference to the stored NewFedoraObjects to be ingested when the final step submits.
  */
 function &islandora_ingest_form_get_objects(array $form_state) {
   return $form_state['islandora']['objects'];
 }
 
 /**
- * Gets a single object.
+ * Gets a single object from the stored NewFedoraObject's.
+ *
+ * @note - In our current use case we are only dealing with a single object ingest, this makes it convenient to access it.
+ *   Ideally the steps implementations will be abstracted to be indifferent to what object it's currently working on. This will act as
+ *   a placeholder for such functionality.
  *
  * @param array $form_state
  *   The drupal form state.
  *
- * @return int
- *   The current step index.
+ * @return array
+ *   Returns the 'current' object in the array of NewFedoraObjects, generally this is only used
+ *   when there is one object in the list of objects.
  */
 function islandora_ingest_form_get_object(array $form_state) {
   $objects = &islandora_ingest_form_get_objects($form_state);
diff --git a/islandora.module b/islandora.module
index 3f649f74..e2d280e5 100644
--- a/islandora.module
+++ b/islandora.module
@@ -436,22 +436,22 @@ function islandora_default_islandora_view_object($object) {
 /**
  * A helper function to get a connection and return an object for objects specified in the menu path as '%islandora_object'.
  *
- * This should only be used by the Drupal menu wildcard system! As for non existing objects this will return page not found.
+ * This should only be used by the Drupal menu wildcard system!
  *
- * After some research drupal_not_found(), drupal_access_denied() and others can not be safetly used at this level. Nor can
- * They be used at the "access callback" level. Not without hacking core, also it seems roling our own versions of these
- * functions will be fruitless. We can still use drupal_goto() though, if we redirect to our own pages for 404, 500 etc. we
- * Will be able to deliever the correct message to users.
+ * When this function returns FALSE the Drupal menu system will issues a "page not found" error, when this function returns NULL,
+ * the access function is expected to check for the given object and return false generating a "accesss denied" error.
  *
- * @todo For non accessible objects to the user this should return access denied.
- * @todo When the repository down this should return a 500 error or a site offline notice.
+ * This will currently display a message if the repository is inaccessable, ideally this would redirect to another page in such a case,
+ * as the access function will not be aware of this fact and will trigger the display of the "access denied" page.
+ *
+ * @todo When the repository down this should return a 500 error or a site offline notice. Currently only displays a message.
  *
  * @param string $object_id
  *   The pid of an object in the menu path identified by '%islandora_object'.
  *
  * @return FedoraObject
- *   If the given object id exists in the repository then this returns a FedoraObject, if no object was found it returns FALSE which triggers a drupal_page_not_found(), if the
- *   object was inaccessible then NULL is returned, and the access callback will catch that case, triggering an access denied.
+ *   If the given object id exists in the repository then this returns a FedoraObject, if no object was found it returns FALSE which triggers drupal_page_not_found(), if the
+ *   object was inaccessible then NULL is returned, and the access callback is expected to catch that case, triggering drupal_access_denied().
  */
 function islandora_object_load($object_id) {
   static $object = NULL, $load_failed = FALSE; // Assume inaccessible.