From 6fd1c9a8044e2fbfcea9a980dc7cabb688fe3bd8 Mon Sep 17 00:00:00 2001
From: Brandon Thomas <echelon@gmail.com>
Date: Mon, 29 Apr 2024 19:57:50 -0400
Subject: [PATCH] documentation

---
 .../list/list_media_files_for_user_handler.rs | 29 ++++++++++++++-----
 .../list/list_media_files_handler.rs          | 29 ++++++++++++++-----
 2 files changed, 44 insertions(+), 14 deletions(-)

diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs
index e293a93213..998ace33f2 100644
--- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs
+++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs
@@ -45,16 +45,31 @@ pub struct ListMediaFilesForUserQueryParams {
   pub page_size: Option<usize>,
   pub page_index: Option<usize>,
 
-  /// NB: This can be one (or more comma-separated values) from `MediaFileType`.
-  /// ?filter_media_type=image or ?filter_media_type=image,video (etc.)
-  pub filter_media_type: Option<String>,
-
-  /// NB: This can be one (or more comma-separated values) from `MediaFileClass`.
-  /// ?filter_media_type=animation or ?filter_media_type=animation,character (etc.)
+  /// NB: This can be one (or more comma-separated values) from `MediaFileClass`,
+  /// which are the broad category of media files: image, video, etc.
+  ///
+  /// Usage:
+  ///   - `?filter_media_classes=audio`
+  ///   - `?filter_media_classes=image,video`
+  ///   - etc.
   pub filter_media_classes: Option<String>,
 
+  /// NB: This can be one (or more comma-separated values) from `MediaFileType`,
+  /// which are mimetype-like / format-like categories of media files: glb, gltf,
+  /// scene_json, etc.
+  ///
+  /// Usage:
+  ///   - `?filter_media_type=scene_json`
+  ///   - `?filter_media_type=glb,gltf`
+  ///   - etc.
+  pub filter_media_type: Option<String>,
+
   /// NB: This can be one (or more comma-separated values) from `MediaFileEngineCategory`.
-  /// ?filter_engine_categories=scene or ?filter_engine_categories=animation,character,object (etc.)
+  ///
+  /// Usage:
+  ///   - `?filter_engine_categories=scene`
+  ///   - `?filter_engine_categories=animation,character,object`
+  ///   - etc.
   pub filter_engine_categories: Option<String>,
 }
 
diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs
index d050d50f06..aeac312851 100644
--- a/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs
+++ b/crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs
@@ -42,16 +42,31 @@ pub struct ListMediaFilesQueryParams {
   pub cursor: Option<String>,
   pub cursor_is_reversed: Option<bool>,
 
-  /// NB: This can be one (or more comma-separated values) from `MediaFileType`.
-  /// ?filter_media_type=image or ?filter_media_type=image,video (etc.)
-  pub filter_media_type: Option<String>,
-
-  /// NB: This can be one (or more comma-separated values) from `MediaFileClass`.
-  /// ?filter_media_type=animation or ?filter_media_type=animation,character (etc.)
+  /// NB: This can be one (or more comma-separated values) from `MediaFileClass`,
+  /// which are the broad category of media files: image, video, etc.
+  ///
+  /// Usage:
+  ///   - `?filter_media_classes=audio`
+  ///   - `?filter_media_classes=image,video`
+  ///   - etc.
   pub filter_media_classes: Option<String>,
 
+  /// NB: This can be one (or more comma-separated values) from `MediaFileType`,
+  /// which are mimetype-like / format-like categories of media files: glb, gltf,
+  /// scene_json, etc.
+  ///
+  /// Usage:
+  ///   - `?filter_media_type=scene_json`
+  ///   - `?filter_media_type=glb,gltf`
+  ///   - etc.
+  pub filter_media_type: Option<String>,
+
   /// NB: This can be one (or more comma-separated values) from `MediaFileEngineCategory`.
-  /// ?filter_engine_categories=scene or ?filter_engine_categories=animation,character,object (etc.)
+  ///
+  /// Usage:
+  ///   - `?filter_engine_categories=scene`
+  ///   - `?filter_engine_categories=animation,character,object`
+  ///   - etc.
   pub filter_engine_categories: Option<String>,
 }