From 01d7bc9e27f0b39d79a94f2f60b6792f5e6e5e1a Mon Sep 17 00:00:00 2001 From: Matthew Raymer Date: Tue, 1 Apr 2025 11:04:19 +0000 Subject: [PATCH] docs: enhance method documentation with standardized patterns Add comprehensive JSDoc documentation to methods in HomeView.vue using standardized patterns: - Add @callGraph sections to document method relationships and dependencies - Add @chain sections to show complete call chains - Add @requires sections to list state and parameter dependencies - Add @modifies sections to document state changes - Enhance parameter and return type documentation - Standardize documentation format across all methods Key methods enhanced: - processRecord() - extractClaim() - extractGiverDid() - getFulfillsPlan() - shouldIncludeRecord() - createFeedRecord() This improves code maintainability by: - Making method relationships explicit - Documenting state dependencies - Clarifying call chains - Standardizing documentation format --- src/views/HomeView.vue | 157 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 145 insertions(+), 12 deletions(-) diff --git a/src/views/HomeView.vue b/src/views/HomeView.vue index 03b2d37..670061d 100644 --- a/src/views/HomeView.vue +++ b/src/views/HomeView.vue @@ -803,12 +803,31 @@ export default class HomeView extends Vue { /** * Updates feed with latest activity - * - Handles filtering of results - * - Updates last viewed claim ID - * - Manages loading state * - * @public - * Called by loadMoreGives() and initializeIdentity() + * @internal + * @callGraph + * Called by: + * - loadMoreGives() + * - initializeIdentity() + * Calls: + * - retrieveGives() + * - processFeedResults() + * - updateFeedLastViewedId() + * - handleFeedError() + * + * @chain + * loadMoreGives() -> updateAllFeed() + * initializeIdentity() -> updateAllFeed() + * + * @requires + * - this.apiServer + * - this.activeDid + * - this.feedPreviousOldestId + * + * @modifies + * - this.isFeedLoading + * - this.feedData (via processFeedResults) + * - this.feedLastViewedClaimId (via updateFeedLastViewedId) */ async updateAllFeed() { this.isFeedLoading = true; @@ -836,7 +855,22 @@ export default class HomeView extends Vue { * Processes feed results and adds them to feedData * * @internal - * Called by updateAllFeed() + * @callGraph + * Called by: updateAllFeed() + * Calls: processRecord() + * + * @chain + * updateAllFeed() -> processFeedResults() + * + * @requires + * - this.feedData + * - this.feedPreviousOldestId + * + * @modifies + * - this.feedData + * - this.feedPreviousOldestId + * + * @param records Array of feed records to process */ private async processFeedResults(records: GiveSummaryRecord[]) { for (const record of records) { @@ -852,7 +886,33 @@ export default class HomeView extends Vue { * Processes a single record and returns it if it passes filters * * @internal - * Called by processFeedResults() + * @callGraph + * Called by: processFeedResults() + * Calls: + * - extractClaim() + * - extractGiverDid() + * - extractRecipientDid() + * - getFulfillsPlan() + * - shouldIncludeRecord() + * - extractProvider() + * - getProvidedByPlan() + * - createFeedRecord() + * + * @chain + * updateAllFeed() -> processFeedResults() -> processRecord() + * + * @requires + * - this.isAnyFeedFilterOn + * - this.isFeedFilteredByVisible + * - this.isFeedFilteredByNearby + * - this.activeDid + * - this.allContacts + * + * @modifies + * - this.feedData (via createFeedRecord) + * + * @param record The record to process + * @returns Processed record with contact info if it passes filters, null otherwise */ private async processRecord(record: GiveSummaryRecord): Promise { const claim = this.extractClaim(record); @@ -874,7 +934,18 @@ export default class HomeView extends Vue { * Extracts claim from record, handling both direct and wrapped claims * * @internal - * Called by processRecord() + * @callGraph + * Called by: processRecord() + * Calls: None + * + * @chain + * processRecord() -> extractClaim() + * + * @requires + * - record.fullClaim + * + * @param record The record containing the claim + * @returns The extracted claim object */ private extractClaim(record: GiveSummaryRecord) { // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -885,7 +956,18 @@ export default class HomeView extends Vue { * Extracts giver DID from claim * * @internal - * Called by processRecord() + * @callGraph + * Called by: processRecord() + * Calls: None + * + * @chain + * processRecord() -> extractGiverDid() + * + * @requires + * - claim.agent + * + * @param claim The claim object containing giver information + * @returns The giver's DID */ private extractGiverDid(claim: any) { // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -907,7 +989,20 @@ export default class HomeView extends Vue { * Gets fulfills plan from cache * * @internal - * Called by processRecord() + * @callGraph + * Called by: processRecord() + * Calls: getPlanFromCache() + * + * @chain + * processRecord() -> getFulfillsPlan() + * + * @requires + * - this.axios + * - this.apiServer + * - this.activeDid + * + * @param record The record containing the plan handle ID + * @returns The fulfills plan object */ private async getFulfillsPlan(record: GiveSummaryRecord) { return await getPlanFromCache( @@ -922,7 +1017,24 @@ export default class HomeView extends Vue { * Checks if record should be included based on filters * * @internal - * Called by processRecord() + * @callGraph + * Called by: processRecord() + * Calls: + * - containsNonHiddenDid() + * - latLongInAnySearchBox() + * + * @chain + * processRecord() -> shouldIncludeRecord() + * + * @requires + * - this.isAnyFeedFilterOn + * - this.isFeedFilteredByVisible + * - this.isFeedFilteredByNearby + * - this.searchBoxes + * + * @param record The record to check + * @param fulfillsPlan The fulfills plan object + * @returns true if record should be included based on filters */ private shouldIncludeRecord(record: GiveSummaryRecord, fulfillsPlan: any): boolean { if (!this.isAnyFeedFilterOn) { @@ -972,7 +1084,28 @@ export default class HomeView extends Vue { * Creates a feed record with contact info * * @internal - * Called by processRecord() + * @callGraph + * Called by: processRecord() + * Calls: + * - didInfoForContact() + * - contactForDid() + * + * @chain + * processRecord() -> createFeedRecord() + * + * @requires + * - this.activeDid + * - this.allContacts + * - this.allMyDids + * + * @param record The base record + * @param claim The claim object + * @param giverDid The giver's DID + * @param recipientDid The recipient's DID + * @param provider The provider object + * @param fulfillsPlan The fulfills plan object + * @param providedByPlan The provided by plan object + * @returns A feed record with contact information */ private createFeedRecord( record: GiveSummaryRecord,