From bab802160f60c8d8d26e75dc69315d9db8429e75 Mon Sep 17 00:00:00 2001
From: Matthew Raymer <mraymer@osinetwork.net>
Date: Tue, 1 Apr 2025 12:30:46 +0000
Subject: [PATCH] docs: add call graph and chain documentation to remaining
 methods

Add comprehensive JSDoc documentation to methods in HomeView.vue:

- latLongInAnySearchBox: Add call chain from shouldIncludeRecord
- giveDescription: Document template usage and displayAmount calls
- displayAmount: Add currency formatting chain
- currencyShortWordForCode: Document amount formatting flow
- openDialog: Document template and openGiftedPrompts usage
- openGiftedPrompts: Add dialog opening chain
- showNameThenIdDialog: Document template usage and prompt flow
- promptForShareMethod: Add sharing flow documentation

Each method now includes:
- @callGraph showing caller/callee relationships
- @chain showing complete execution paths
- @requires listing dependencies
- Enhanced parameter documentation

This completes the standardized documentation pattern across all methods,
making method relationships and dependencies explicit.
---
 src/views/HomeView.vue | 107 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 99 insertions(+), 8 deletions(-)

diff --git a/src/views/HomeView.vue b/src/views/HomeView.vue
index 670061d5..65dd42fa 100644
--- a/src/views/HomeView.vue
+++ b/src/views/HomeView.vue
@@ -783,7 +783,16 @@ export default class HomeView extends Vue {
    * Checks if coordinates fall within any search box
    * 
    * @internal
-   * Called by shouldIncludeRecord() for location-based filtering
+   * @callGraph
+   * Called by: shouldIncludeRecord()
+   * Calls: None
+   * 
+   * @chain
+   * shouldIncludeRecord() -> latLongInAnySearchBox()
+   * 
+   * @requires
+   * - this.searchBoxes
+   * 
    * @param lat Latitude to check
    * @param long Longitude to check
    * @returns true if coordinates are within any search box
@@ -1230,7 +1239,20 @@ export default class HomeView extends Vue {
    * Formats gift description with giver and recipient info
    * 
    * @public
-   * Used in template for displaying gift descriptions
+   * @callGraph
+   * Called by: Template
+   * Calls: displayAmount()
+   * 
+   * @chain
+   * Template -> giveDescription() -> displayAmount() -> currencyShortWordForCode()
+   * 
+   * @requires
+   * - giveRecord.fullClaim
+   * - giveRecord.giver
+   * - giveRecord.receiver
+   * - giveRecord.recipientProjectName
+   * - giveRecord.providerPlanName
+   * 
    * @param giveRecord Record containing gift information
    * @returns formatted description string
    */
@@ -1342,7 +1364,20 @@ export default class HomeView extends Vue {
    * Formats amount with currency code
    * 
    * @internal
-   * Called by giveDescription()
+   * @callGraph
+   * Called by: giveDescription()
+   * Calls: currencyShortWordForCode()
+   * 
+   * @chain
+   * giveDescription() -> displayAmount() -> currencyShortWordForCode()
+   * 
+   * @requires
+   * - code: string (currency code)
+   * - amt: number (amount to format)
+   * 
+   * @param code Currency code
+   * @param amt Amount to format
+   * @returns formatted amount string
    */
   displayAmount(code: string, amt: number) {
     return "" + amt + " " + this.currencyShortWordForCode(code, amt === 1);
@@ -1352,7 +1387,20 @@ export default class HomeView extends Vue {
    * Gets currency word based on code and plurality
    * 
    * @internal
-   * Called by displayAmount()
+   * @callGraph
+   * Called by: displayAmount()
+   * Calls: None
+   * 
+   * @chain
+   * giveDescription() -> displayAmount() -> currencyShortWordForCode()
+   * 
+   * @requires
+   * - unitCode: string (currency code)
+   * - single: boolean (whether to use singular form)
+   * 
+   * @param unitCode Currency code
+   * @param single Whether to use singular form
+   * @returns formatted currency word
    */
   currencyShortWordForCode(unitCode: string, single: boolean) {
     return unitCode === "HUR" ? (single ? "hour" : "hours") : unitCode;
@@ -1362,7 +1410,20 @@ export default class HomeView extends Vue {
    * Opens dialog for creating new gift/claim
    * 
    * @public
-   * Called by template and openGiftedPrompts()
+   * @callGraph
+   * Called by: 
+   * - Template
+   * - openGiftedPrompts()
+   * Calls: GiftedDialog.open()
+   * 
+   * @chain
+   * Template -> openDialog()
+   * openGiftedPrompts() -> openDialog()
+   * 
+   * @requires
+   * - this.$refs.customDialog
+   * - this.activeDid
+   * 
    * @param giver Optional contact info for giver
    * @param description Optional gift description
    */
@@ -1383,7 +1444,17 @@ export default class HomeView extends Vue {
    * Opens prompts for gift ideas
    * 
    * @public
-   * Called by template click handler
+   * @callGraph
+   * Called by: Template
+   * Calls: openDialog()
+   * 
+   * @chain
+   * Template -> openGiftedPrompts() -> openDialog()
+   * 
+   * @requires
+   * - this.$refs.giftedPrompts
+   * 
+   * @param callback Function to handle selected gift info
    */
   openGiftedPrompts() {
     (this.$refs.giftedPrompts as GiftedPrompts).open((giver, description) =>
@@ -1436,7 +1507,18 @@ export default class HomeView extends Vue {
    * Shows name input dialog if needed
    * 
    * @public
-   * Called by template click handler
+   * @callGraph
+   * Called by: Template
+   * Calls: 
+   * - UserNameDialog.open()
+   * - promptForShareMethod()
+   * 
+   * @chain
+   * Template -> showNameThenIdDialog() -> promptForShareMethod()
+   * 
+   * @requires
+   * - this.$refs.userNameDialog
+   * - this.givenName
    */
   showNameThenIdDialog() {
     if (!this.givenName) {
@@ -1452,7 +1534,16 @@ export default class HomeView extends Vue {
    * Shows dialog for sharing method selection
    * 
    * @internal
-   * Called by showNameThenIdDialog()
+   * @callGraph
+   * Called by: showNameThenIdDialog()
+   * Calls: ChoiceButtonDialog.open()
+   * 
+   * @chain
+   * Template -> showNameThenIdDialog() -> promptForShareMethod()
+   * 
+   * @requires
+   * - this.$refs.choiceButtonDialog
+   * - this.$router
    */
   promptForShareMethod() {
     (this.$refs.choiceButtonDialog as ChoiceButtonDialog).open({