PHPDoc

5 files changed, 197 insertions, 33 deletions

diff --git a/modules_v3/batch_update/admin_batch_update.php b/modules_v3/batch_update/admin_batch_update.php
index d7c28957ee..e5d119b17e 100644
--- a/modules_v3/batch_update/admin_batch_update.php
+++ b/modules_v3/batch_update/admin_batch_update.php
@@ -35,7 +35,11 @@ class batch_update {
 	var $next_xref=null; // The next xref to process
 	var $record   =null; // A GedcomRecord object corresponding to $curr_xref
 
-	// Main entry point - called by the webtrees framework in response to module.php?mod=batch_update
+	/**
+	 * Main entry point - called by the webtrees framework in response to module.php?mod=batch_update
+	 *
+	 * @return string
+	 */
 	function main() {
 		// HTML common to all pages
 		$html=
@@ -95,10 +99,13 @@ class batch_update {
 			}
 		}
 		$html.='</table></form>';
+
 		return $html;
 	}
 
-	// Constructor - initialise variables and validate user-input
+	/**
+	 * Constructor - initialise variables and validate user-input
+	 */
 	public function __construct() {
 		$this->plugins=self::getPluginList();    // List of available plugins
 		$this->plugin =WT_Filter::get('plugin'); // User parameters
@@ -170,7 +177,13 @@ class batch_update {
 		}
 	}
 
-	// Find the next record that needs to be updated
+	/**
+	 * Find the next record that needs to be updated.
+	 *
+	 * @param string $xref
+	 *
+	 * @return string|null
+	 */
 	function findNextXref($xref) {
 		foreach (array_keys($this->all_xrefs) as $key) {
 			if ($key>$xref) {
@@ -183,7 +196,13 @@ class batch_update {
 		return null;
 	}
 
-	// Find the previous record that needs to be updated
+	/**
+	 * Find the previous record that needs to be updated.
+	 *
+	 * @param string $xref
+	 *
+	 * @return string|null
+	 */
 	function findPrevXref($xref) {
 		foreach (array_reverse(array_keys($this->all_xrefs)) as $key) {
 			if ($key<$xref) {
@@ -196,6 +215,9 @@ class batch_update {
 		return null;
 	}
 
+	/**
+	 * Generate a list of all XREFs.
+	 */
 	function getAllXrefs() {
 		$sql=array();
 		$vars=array();
@@ -231,7 +253,11 @@ class batch_update {
 			->fetchAssoc();
 	}
 
-	// Scan the plugin folder for a list of plugins
+	/**
+	 * Scan the plugin folder for a list of plugins
+	 *
+	 * @return base_plugin[]
+	 */
 	static function getPluginList() {
 		$array=array();
 		$dir=dirname(__FILE__).'/plugins/';
@@ -244,10 +270,15 @@ class batch_update {
 			}
 		}
 		closedir($dir_handle);
+
 		return $array;
 	}
 
-	// Javascript that gets included on every page
+	/**
+	 * Javascript that gets included on every page
+	 *
+	 * @return string
+	 */
 	static function getJavascript() {
 		return
 			'<script>'.
@@ -261,7 +292,16 @@ class batch_update {
 		;
 	}
 
-	// Create a submit button for our form
+	/**
+	 * Create a submit button for our form
+	 *
+	 * @param string $text
+	 * @param string $xref
+	 * @param string $action
+	 * @param string $data
+	 *
+	 * @return string
+	 */
 	static function createSubmitButton($text, $xref, $action='', $data='') {
 		return
 			'<input type="submit" value="'.$text.'" onclick="'.
@@ -272,40 +312,67 @@ class batch_update {
 			($xref ? '' : ' disabled').'>';
 	}
 
-	// Get the current view of a record, allowing for pending changes
+	/**
+	 * Get the current view of a record, allowing for pending changes
+	 *
+	 * @param string $xref
+	 * @param string $type
+	 *
+	 * @return string
+	 */
 	static function getLatestRecord($xref, $type) {
 		switch ($type) {
-		case 'INDI': return WT_Individual::getInstance($xref)->getGedcom();
-		case 'FAM':  return WT_Family::getInstance($xref)->getGedcom();
-		case 'SOUR': return WT_Source::getInstance($xref)->getGedcom();
-		case 'REPO': return WT_Repository::getInstance($xref)->getGedcom();
-		case 'OBJE': return WT_Media::getInstance($xref)->getGedcom();
-		case 'NOTE': return WT_Note::getInstance($xref)->getGedcom();
-		default:     return WT_GedcomRecord::getInstance($xref)->getGedcom();
+		case 'INDI':
+			return WT_Individual::getInstance($xref)->getGedcom();
+		case 'FAM':
+			return WT_Family::getInstance($xref)->getGedcom();
+		case 'SOUR':
+			return WT_Source::getInstance($xref)->getGedcom();
+		case 'REPO':
+			return WT_Repository::getInstance($xref)->getGedcom();
+		case 'OBJE':
+			return WT_Media::getInstance($xref)->getGedcom();
+		case 'NOTE':
+			return WT_Note::getInstance($xref)->getGedcom();
+		default:
+			return WT_GedcomRecord::getInstance($xref)->getGedcom();
 		}
 	}
 }
 
-// Each plugin should extend the base_plugin class, and implement these
-// two functions:
-//
-//  bool doesRecordNeedUpdate($xref, $gedrec)
-//  string updateRecord($xref, $gedrec)
-//
+/**
+ * Class base_plugin
+ *
+ * Each plugin should extend the base_plugin class, and implement these
+ * two functions:
+ *
+ * bool doesRecordNeedUpdate($xref, $gedrec)
+ * string updateRecord($xref, $gedrec)
+ */
 class base_plugin {
 	var $chan=false; // User option; update change record
 
-	// Default is to operate on INDI records
+	/**
+	 * Default is to operate on INDI records
+	 *
+	 * @return string[]
+	 */
 	function getRecordTypesToUpdate() {
 		return array('INDI');
 	}
 
-	// Default option is just the "don't update CHAN record"
+	/**
+	 * Default option is just the "don't update CHAN record"
+	 */
 	function getOptions() {
 		$this->chan=WT_Filter::getBool('chan');
 	}
 
-	// Default option is just the "don't update CHAN record"
+	/**
+	 * Default option is just the "don't update CHAN record"
+	 *
+	 * @return string
+	 */
 	function getOptionsForm() {
 		return
 			'<tr><th>'.WT_I18N::translate('Do not update the “last change” record').'</th>'.
@@ -315,7 +382,13 @@ class base_plugin {
 			'</select></td></tr>';
 	}
 
-	// Default buttons are update and update_all
+	/**
+	 * Default buttons are update and update_all
+	 *
+	 * @param string $xref
+	 *
+	 * @return string[]
+	 */
 	function getActionButtons($xref) {
 		if (Auth::user()->getPreference('auto_accept')) {
 			return array(
@@ -329,7 +402,13 @@ class base_plugin {
 		}
 	}
 
-	// Default previewer for plugins with no custom preview.
+	/**
+	 * Default previewer for plugins with no custom preview.
+	 *
+	 * @param WT_GedcomRecord $record
+	 *
+	 * @return string
+	 */
 	function getActionPreview(WT_GedcomRecord $record) {
 		$old_lines=preg_split('/[\n]+/', $record->getGedcom());
 		$new_lines=preg_split('/[\n]+/', $this->updateRecord($record->getXref(), $record->getGedcom()));
@@ -361,7 +440,18 @@ class base_plugin {
 		return '<pre>'.self::createEditLinks(implode("\n", $diff_lines)).'</pre>';
 	}
 
-	// Longest Common Subsequence.
+	/**
+	 * Longest Common Subsequence.
+	 *
+	 * @param string[] $X
+	 * @param string[] $Y
+	 * @param integer  $x1
+	 * @param integer  $x2
+	 * @param integer  $y1
+	 * @param integer  $y2
+	 *
+	 * @return array
+	 */
 	private static function LongestCommonSubsequence($X, $Y, $x1, $x2, $y1, $y2) {
 		if ($x2-$x1>=0 && $y2-$y1>=0) {
 			if ($X[$x1]==$Y[$y1]) {
@@ -386,16 +476,35 @@ class base_plugin {
 		}
 	}
 
-	// Decorate inserted/deleted text
+	/**
+	 * Decorate inserted text
+	 *
+	 * @param string $text
+	 *
+	 * @return string
+	 */
 	static function decorateInsertedText($text) {
 		return '<span class="added_text">'.$text.'</span>';
 	}
 
+	/**
+	 * Decorate deleted text
+	 *
+	 * @param string $text
+	 *
+	 * @return string
+	 */
 	static function decorateDeletedText($text) {
 		return '<span class="deleted_text">'.$text.'</span>';
 	}
 
-	// Converted gedcom links into editable links
+	/**
+	 * Converted gedcom links into editable links
+	 *
+	 * @param string $gedrec
+	 *
+	 * @return string
+	 */
 	static function createEditLinks($gedrec) {
 		return preg_replace(
 			"/@([^#@\n]+)@/m",
diff --git a/modules_v3/faq/module.php b/modules_v3/faq/module.php
index d67633a23f..454205f99b 100644
--- a/modules_v3/faq/module.php
+++ b/modules_v3/faq/module.php
@@ -72,7 +72,9 @@ class faq_WT_Module extends WT_Module implements WT_Module_Menu, WT_Module_Confi
 		return 'module.php?mod=' . $this->getName() . '&amp;mod_action=admin_config';
 	}
 
-	// Action from the configuration page
+	/**
+	 * Action from the configuration page
+	 */
 	private function edit() {
 		require_once WT_ROOT . 'includes/functions/functions_edit.php';
 
diff --git a/modules_v3/html/module.php b/modules_v3/html/module.php
index 7fe40964da..3eb2886508 100644
--- a/modules_v3/html/module.php
+++ b/modules_v3/html/module.php
@@ -157,7 +157,7 @@ class html_WT_Module extends WT_Module implements WT_Module_Block {
 
 			WT_I18N::translate('Statistics')=>
 			'<div class="gedcom_stats">
-				<span style="font-weight: bold"><a href="index.php?command=gedcom">#gedcomTitle#</a></span><br>
+				<span style="font-weight: bold;"><a href="index.php?command=gedcom">#gedcomTitle#</a></span><br>
 				' . WT_I18N::translate('This family tree was last updated on %s.', '#gedcomUpdated#') . '
 				<table id="keywords">
 					<tr>
@@ -244,7 +244,7 @@ class html_WT_Module extends WT_Module implements WT_Module_Block {
 									<td class="facts_value">#largestFamily#</td>
 								</tr>
 								<tr>
-									<td class="facts_label">'.WT_I18N::translate('Average number of children per family').'</td>
+									<td class="facts_label">'.WT_I18N::translate('Average number of children per family'). '</td>
 									<td class="facts_value" align="right">#averageChildren#</td>
 									<td class="facts_value"></td>
 								</tr>
@@ -252,7 +252,7 @@ class html_WT_Module extends WT_Module implements WT_Module_Block {
 						</td>
 					</tr>
 				</table><br>
-				<span style="font-weight: bold">'.WT_I18N::translate('Most common surnames').'</span><br>
+				<span style="font-weight: bold;">' .WT_I18N::translate('Most common surnames').'</span><br>
 				#commonSurnames#
 			</div>'
 		);
diff --git a/modules_v3/individuals/module.php b/modules_v3/individuals/module.php
index 505e4fb38b..01eeda3353 100644
--- a/modules_v3/individuals/module.php
+++ b/modules_v3/individuals/module.php
@@ -156,9 +156,16 @@ class individuals_WT_Module extends WT_Module implements WT_Module_Sidebar {
 		$out .= '</p>';
 		$out .= '<div id="sb_indi_content">';
 		$out .= '</div></form>';
+
 		return $out;
 	}
 
+	/**
+	 * @param string $alpha
+	 * @param string $surname1
+	 *
+	 * @return string
+	 */
 	public function getAlphaSurnames($alpha, $surname1='') {
 		$surnames = WT_Query_Name::surnames('', $alpha, true, false, WT_GED_ID);
 		$out = '<ul>';
@@ -174,9 +181,16 @@ class individuals_WT_Module extends WT_Module implements WT_Module_Sidebar {
 			$out .= '</li>';
 		}
 		$out .= '</ul>';
+
 		return $out;
 	}
 
+	/**
+	 * @param string $alpha
+	 * @param string $surname
+	 *
+	 * @return string
+	 */
 	public function getSurnameIndis($alpha, $surname) {
 		$indis=WT_Query_Name::individuals($surname, $alpha, '', true, false, WT_GED_ID);
 		$out = '<ul>';
@@ -193,9 +207,15 @@ class individuals_WT_Module extends WT_Module implements WT_Module_Sidebar {
 			}
 		}
 		$out .= '</ul>';
+
 		return $out;
 	}
 
+	/**
+	 * @param string $query
+	 *
+	 * @return string
+	 */
 	public function search($query) {
 		if (strlen($query)<2) {
 			return '';
@@ -225,6 +245,7 @@ class individuals_WT_Module extends WT_Module implements WT_Module_Sidebar {
 			}
 		}
 		$out .= '</ul>';
+
 		return $out;
 	}
 }
diff --git a/modules_v3/personal_facts/module.php b/modules_v3/personal_facts/module.php
index d64287bd7d..719e1df1fd 100644
--- a/modules_v3/personal_facts/module.php
+++ b/modules_v3/personal_facts/module.php
@@ -202,6 +202,16 @@ class personal_facts_WT_Module extends WT_Module implements WT_Module_Tab {
 		return $facts;
 	}
 
+	/**
+	 * Get the events of children and grandchildren.
+	 *
+	 * @param WT_Individual $person
+	 * @param WT_Family     $family
+	 * @param string        $option
+	 * @param string        $relation
+	 *
+	 * @return WT_Fact[]
+	 */
 	private static function childFacts(WT_Individual $person, WT_Family $family, $option, $relation) {
 		global $controller, $SHOW_RELATIVES_EVENTS;
 
@@ -325,6 +335,14 @@ class personal_facts_WT_Module extends WT_Module implements WT_Module_Tab {
 		return $facts;
 	}
 
+	/**
+	 * Get the events of parents and grandparents.
+	 *
+	 * @param WT_Individual $person
+	 * @param integer       $sosa
+	 *
+	 * @return WT_Fact[]
+	 */
 	private static function parentFacts(WT_Individual $person, $sosa) {
 		global $controller, $SHOW_RELATIVES_EVENTS;
 
@@ -416,6 +434,13 @@ class personal_facts_WT_Module extends WT_Module implements WT_Module_Tab {
 		return $facts;
 	}
 
+	/**
+	 * Get any historical events.
+	 *
+	 * @param WT_Individual $person
+	 *
+	 * @return WT_Fact[]
+	 */
 	private static function historicalFacts(WT_Individual $person) {
 		global $SHOW_RELATIVES_EVENTS;
 
@@ -445,6 +470,13 @@ class personal_facts_WT_Module extends WT_Module implements WT_Module_Tab {
 		return $facts;
 	}
 
+	/**
+	 * Get the events of associates.
+	 *
+	 * @param WT_Individual $person
+	 *
+	 * @return WT_Fact[]
+	 */
 	private static function associateFacts(WT_Individual $person) {
 		$facts = array();