Changeset 25508 for trunk

Timestamp:

Nov 17, 2013, 5:57:04 PM (11 years ago)

Author:

mistic100

Message:

feature 2999 : documentation of include/functions_category.inc.php

File:

• trunk/include/functions_category.inc.php (modified) (13 diffs)

trunk/include/functions_category.inc.php

@@ -23 +23 @@
 
 /**
- * Provides functions to handle categories.
- *
- *
- */
+ * @package functions\category
+ */
+
+
+/**
+ * Callback used for sorting by global_rank
+ */
+function global_rank_compare($a, $b)
+{
+  return strnatcasecmp($a['global_rank'], $b['global_rank']);
+}
+
+/**
+ * Callback used for sorting by rank
+ */
+function rank_compare($a, $b)
+{
+  return $a['rank'] - $b['rank'];
+}
 
 /**
  * Is the category accessible to the connected user ?
- *
- * Note : if the user is not authorized to see this category, page creation
- * ends (exit command in this function)
- *
- * @param int category id to verify
- * @return void
+ * If the user is not authorized to see this category, script exits
+ *
+ * @param int $category_id
  */
 function check_restrictions($category_id)
@@ -49 +61 @@
 }
 
+/**
+ * Returns template vars for main categories menu.
+ *
+ * @return array[]
+ */
 function get_categories_menu()
 {
@@ -144 +161 @@
 }
 
-
-/**
- * Retrieve informations about a category in the database
- *
- * Returns an array with following keys :
- *
- *  - comment
- *  - dir : directory, might be empty for virtual categories
- *  - name : an array with indexes from 0 (lowest cat name) to n (most
- *           uppercat name findable)
- *  - nb_images
- *  - id_uppercat
- *  - site_id
- *  -
- *
- * @param int category id
+/**
+ * Retrieves informations about a category.
+ *
+ * @param int $id
  * @return array
  */
-function get_cat_info( $id )
+function get_cat_info($id)
 {
   $query = '
@@ -213 +218 @@
 }
 
-
-
-// returns an array of image orders available for users/visitors
+/**
+ * Returns an array of image orders available for users/visitors.
+ * Each entry is an array containing
+ *  0: name
+ *  1: SQL ORDER command
+ *  2: visiblity (true or false)
+ *
+ * @return array[]
+ */
 function get_category_preferred_image_orders()
 {
@@ -236 +247 @@
 }
 
+/**
+ * Assign a template var useable with {html_options} from a list of categories
+ *
+ * @param array[] $categories (at least id,name,global_rank,uppercats for each)
+ * @param int[] $selected ids of selected items
+ * @param string $blockname variable name in template
+ * @param bool $fullname full breadcrumb or not
+ */
 function display_select_categories($categories,
                                    $selecteds,
@@ -275 +294 @@
 }
 
-function display_select_cat_wrapper($query, $selecteds, $blockname,
+/**
+ * Same as display_select_categories but categories are ordered by rank
+ * @see display_select_categories()
+ */
+function display_select_cat_wrapper($query,
+                                    $selecteds,
+                                    $blockname,
                                     $fullname = true)
 {
@@ -284 +309 @@
 
 /**
- * returns all subcategory identifiers of given category ids
- *
- * @param array ids
- * @return array
+ * Returns all subcategory identifiers of given category ids
+ *
+ * @param int[] $ids
+ * @return int[]
  */
 function get_subcat_ids($ids)
@@ -314 +339 @@
 }
 
-/** finds a matching category id from a potential list of permalinks
- * @param array permalinks example: holiday holiday/france holiday/france/paris
- * @param int idx - output of the index in $permalinks that matches
- * return category id or null if no match
- */
-function get_cat_id_from_permalinks( $permalinks, &$idx )
+/**
+ * Finds a matching category id from a potential list of permalinks
+ *
+ * @param string[] $permalinks
+ * @param int $idx filled with the index in $permalinks that matches
+ * @return int|null
+ */
+function get_cat_id_from_permalinks($permalinks, &$idx)
 {
   $in = '';
@@ -360 +387 @@
 }
 
-function global_rank_compare($a, $b)
-{
-  return strnatcasecmp($a['global_rank'], $b['global_rank']);
-}
-
-function rank_compare($a, $b)
-{
-  return $a['rank'] - $b['rank'];
-}
-
-/**
- * returns display text for information images of category
- *
- * @param array categories
+/**
+ * Returns display text for images counter of category
+ *
+ * @param int $cat_nb_images nb images directly in category
+ * @param int $cat_count_images nb images in category (including subcats)
+ * @param int $cat_count_categories nb subcats
+ * @param bool $short_message if true append " in this album"
+ * @param string $separator
  * @return string
  */
-function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_categories, $short_message = true, $Separator = '\n')
+function get_display_images_count($cat_nb_images, $cat_count_images, $cat_count_categories, $short_message = true, $separator = '\n')
 {
   $display_text = '';
@@ -384 +405 @@
     if ($cat_nb_images > 0 and $cat_nb_images < $cat_count_images)
     {
-      $display_text.= get_display_images_count($cat_nb_images, $cat_nb_images, 0, $short_message, $Separator).$Separator;
+      $display_text.= get_display_images_count($cat_nb_images, $cat_nb_images, 0, $short_message, $separator).$separator;
       $cat_count_images-= $cat_nb_images;
       $cat_nb_images = 0;
@@ -395 +416 @@
     {
       //no descendant categories or descendants do not contain images
-      if (! $short_message)
+      if (!$short_message)
       {
         $display_text.= ' '.l10n('in this album');
@@ -410 +431 @@
 
 /**
- * Find a random photo among all photos below a given album in the tree (not
- * only photo directly associated to the album but also to sub-albums)
- *
- * we need $category['uppercats'], $category['id'], $category['count_images']
+ * Find a random photo among all photos inside an album (including sub-albums)
+ *
+ * @param array $category (at least id,uppercats,count_images)
+ * @param bool $recursive
+ * @return int|null
  */
 function get_random_image_in_category($category, $recursive=true)
@@ -459 +481 @@
 }
 
-
 ?>