Refactor: Implement documentation plan

src/hooks/privacy/usePrivacyMutations.ts

@@ -8,7 +8,35 @@ import type { PrivacyFormData } from '@/types/privacy';
 
 /**
  * Hook for privacy settings mutations
- * Provides: privacy settings updates with automatic audit logging and cache invalidation
+ * 
+ * Features:
+ * - Update privacy level and visibility settings
+ * - Optimistic updates with rollback on error
+ * - Automatic audit trail logging
+ * - Smart cache invalidation affecting search visibility
+ * - Updates both profile and user_preferences tables
+ * 
+ * Modifies:
+ * - `profiles` table (privacy_level, show_pronouns)
+ * - `user_preferences` table (privacy_settings)
+ * - `profile_audit_log` table (audit trail)
+ * 
+ * Cache Invalidation:
+ * - User profile data (`invalidateUserProfile`)
+ * - Audit logs (`invalidateAuditLogs`)
+ * - User search results (`invalidateUserSearch`) - privacy affects visibility
+ * 
+ * @example
+ * ```tsx
+ * const { updatePrivacy, isUpdating } = usePrivacyMutations();
+ * 
+ * updatePrivacy.mutate({
+ *   privacy_level: 'private',
+ *   show_pronouns: false,
+ *   show_email: false,
+ *   show_location: true
+ * });
+ * ```
  */
 export function usePrivacyMutations() {
   const { user } = useAuth();

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 { 

src/hooks/reports/useReportMutation.ts

@@ -12,6 +12,34 @@ interface ReportParams {
   reason?: string;
 }
 
+/**
+ * Hook for content reporting mutations
+ * 
+ * Features:
+ * - Submit reports for review/profile/submission abuse
+ * - Automatic moderation queue invalidation
+ * - Audit logging via database trigger
+ * - User-friendly success/error notifications
+ * 
+ * Modifies:
+ * - `reports` table
+ * 
+ * Cache Invalidation:
+ * - Moderation queue (`invalidateModerationQueue`)
+ * - Moderation stats (`invalidateModerationStats`)
+ * 
+ * @example
+ * ```tsx
+ * const mutation = useReportMutation();
+ * 
+ * mutation.mutate({
+ *   entityType: 'review',
+ *   entityId: 'review-123',
+ *   reportType: 'spam',
+ *   reason: 'This is clearly spam content'
+ * });
+ * ```
+ */
 export function useReportMutation() {
   const { user } = useAuth();
   const queryClient = useQueryClient();