From 3d96cba76a0b5ea213197ff7fcfa5bcf202795c5 Mon Sep 17 00:00:00 2001
From: tjhunt <tjhunt>
Date: Wed, 12 Dec 2007 17:10:48 +0000
Subject: [PATCH] Improve PHP doc comments.

---
 lib/datalib.php  | 14 ++++++++++----
 lib/grouplib.php |  1 +
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/lib/datalib.php b/lib/datalib.php
index abbb1f58065..2343a46c4bf 100644
--- a/lib/datalib.php
+++ b/lib/datalib.php
@@ -1678,15 +1678,21 @@ function get_all_instances_in_courses($modulename, $courses, $userid=NULL, $incl
 }
 
 /**
- * Returns an array of all the active instances of a particular module in a given course, sorted in the order they are defined
+ * Returns an array of all the active instances of a particular module in a given course,
+ * sorted in the order they are defined.
  *
  * Returns an array of all the active instances of a particular
  * module in a given course, sorted in the order they are defined
- * in the course.   Returns false on any errors.
+ * in the course. Returns an empty array on any errors.
+ *
+ * The returned objects includle the columns cw.section, cm.visible,
+ * cm.groupmode and cm.groupingid, and are indexed by cm.id.
  *
  * @uses $CFG
- * @param string  $modulename The name of the module to get instances for
- * @param object(course)  $course This depends on an accurate $course->modinfo
+ * @param string $modulename The name of the module to get instances for
+ * @param object $course This depends on an accurate $course->modinfo
+ * @return array of module instance objects, including some extra fields from the course_modules
+ *          and course_sections tables, or an empty array if an error occurred.
  */
 function get_all_instances_in_course($modulename, $course, $userid=NULL, $includeinvisible=false) {
 
diff --git a/lib/grouplib.php b/lib/grouplib.php
index 55ab489183b..6bbe49bab9c 100644
--- a/lib/grouplib.php
+++ b/lib/grouplib.php
@@ -258,6 +258,7 @@ function groups_get_course_groupmode($course) {
 /**
  * Returns effective groupmode used in activity, course setting
  * overrides activity setting if groupmodeforce enabled.
+ * @param $cm the course module object. Only the ->course and ->groupmode need to be set.
  * @return integer group mode
  */
 function groups_get_activity_groupmode($cm) {