diff --git a/web/packages/new/photos/types/file.ts b/web/packages/new/photos/types/file.ts
index db5742b294..4426c35116 100644
--- a/web/packages/new/photos/types/file.ts
+++ b/web/packages/new/photos/types/file.ts
@@ -110,6 +110,14 @@ export interface FileWithUpdatedPublicMagicMetadata {
 }
 
 export interface FileMagicMetadataProps {
+    /**
+     * The visibility of the file
+     *
+     * The file's visibility is user specific attribute, and thus we keep it in
+     * the private magic metadata. This allows the file's owner to share a file
+     * and edit its visibility without making revealing their visibility
+     * preference to the people with whom they have shared the file.
+     */
     visibility?: FileVisibility;
     filePaths?: string[];
 }
diff --git a/web/packages/new/photos/types/magicMetadata.ts b/web/packages/new/photos/types/magicMetadata.ts
index c443a7425f..fcd4560ee6 100644
--- a/web/packages/new/photos/types/magicMetadata.ts
+++ b/web/packages/new/photos/types/magicMetadata.ts
@@ -7,6 +7,9 @@ export interface MagicMetadataCore<T> {
 
 export type EncryptedMagicMetadata = MagicMetadataCore<string>;
 
+/**
+ * The visibility of an {@link EnteFile}.
+ */
 export enum FileVisibility {
     VISIBLE = 0,
     ARCHIVED = 1,