Refactor: Implement documentation plan

src/hooks/profile/useProfileUpdateMutation.ts

@@ -15,6 +15,39 @@ interface ProfileUpdateParams {
   };
 }
 
+/**
+ * Hook for profile update mutations
+ * 
+ * Features:
+ * - Optimistic updates for instant UI feedback
+ * - Automatic rollback on error
+ * - Smart cache invalidation (profile, stats, activity)
+ * - Conditional search invalidation when name changes
+ * - Comprehensive error handling with toast notifications
+ * 
+ * Modifies:
+ * - `profiles` table
+ * 
+ * Cache Invalidation:
+ * - User profile data (`invalidateUserProfile`)
+ * - Profile stats (`invalidateProfileStats`)
+ * - Profile activity feed (`invalidateProfileActivity`)
+ * - User search results if name changed (`invalidateUserSearch`)
+ * 
+ * @example
+ * ```tsx
+ * const mutation = useProfileUpdateMutation();
+ * 
+ * mutation.mutate({
+ *   userId: user.id,
+ *   updates: {
+ *     display_name: 'New Name',
+ *     bio: 'Updated bio',
+ *     website: 'https://example.com'
+ *   }
+ * });
+ * ```
+ */
 export function useProfileUpdateMutation() {
   const queryClient = useQueryClient();
   const {