improve endpoint documentation

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/delete/delete_media_file_handler.rs

@@ -64,6 +64,7 @@ impl fmt::Display for DeleteMediaFileError {
 
 // =============== Handler ===============
 
+/// Delete a media file. (Files and records are soft deleted.)
 #[utoipa::path(
     delete,
     tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/change_media_file_visibility_handler.rs

@@ -63,6 +63,7 @@ impl fmt::Display for ChangeMediaFileVisibilityError {
 
 // =============== Handler ===============
 
+/// Change the visibility (public, hidden, private) of a media file.
 #[utoipa::path(
     post,
     tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/rename_media_file_handler.rs

@@ -65,6 +65,7 @@ impl fmt::Display for RenameMediaFileError {
 
 // =============== Handler ===============
 
+/// Change (or remove) the "title" of a media file.
 #[utoipa::path(
   post,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/edit/set_media_file_cover_image_handler.rs

@@ -68,6 +68,10 @@ impl fmt::Display for SetMediaFileCoverImageError {
 
 // =============== Handler ===============
 
+/// Set or remove the "cover image" (which are used as thumbnails) on a file.
+///
+/// The cover image is another media file of media_class = image. It can be anything in the database,
+/// you'll just need its media file token.
 #[utoipa::path(
   post,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/batch_get_media_files_handler.rs

@@ -210,6 +210,7 @@ impl fmt::Display for BatchGetMediaFilesError {
 
 // =============== Handler ===============
 
+/// List many media files at the same time by supplying their tokens. You'll have to provide the tokens.
 #[utoipa::path(
   get,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/get/get_media_file_handler.rs

@@ -192,6 +192,7 @@ impl fmt::Display for GetMediaFileError {
   }
 }
 
+/// Get a single media file by token.
 #[utoipa::path(
   get,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_featured_media_files_handler.rs

@@ -124,6 +124,7 @@ impl ResponseError for ListFeaturedMediaFilesError {
   }
 }
 
+/// List media files that were featured or promoted by the staff (paginated). This will power our global asset drawers and highlight reels.
 #[utoipa::path(
   get,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_by_batch_token_handler.rs

@@ -147,6 +147,10 @@ impl std::fmt::Display for ListMediaFilesByBatchError {
   }
 }
 
+/// List media files that were generated together in a "batch", e.g. stable diffusion outputs.
+///
+/// This uses a special "batch token" that these jobs return. Media files created together will also
+/// return their batch token in the GET endpoint so that you can render a gallery of the batch outputs.
 #[utoipa::path(
   get,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_for_user_handler.rs

@@ -175,6 +175,10 @@ impl std::fmt::Display for ListMediaFilesForUserError {
   }
 }
 
+/// List all of a user's media files (paginated).
+///
+/// This endpoint uses the session to automatically show all files for the given user, but only
+/// show "public" files for external users.
 #[utoipa::path(
   get,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/list/list_media_files_handler.rs

@@ -177,6 +177,9 @@ impl std::fmt::Display for ListMediaFilesError {
   }
 }
 
+/// List all media files in the system globally, across all users (paginated).
+///
+/// This powers "explore files" page.
 #[utoipa::path(
   get,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_new_scene_media_file_handler.rs

@@ -67,6 +67,13 @@ pub struct UploadNewSceneMediaFileSuccessResponse {
   pub media_file_token: MediaFileToken,
 }
 
+/// This endpoint is for saving a new scene for the first time.
+///
+/// You'll get back a media token for accessing and querying the scene in the future.
+///
+/// For future saving on the same scene, call the "saved scene" endpoint, i.e. do not
+/// call this endpoint a second time unless the user wants to save a new copy of the
+/// same scene.
 #[utoipa::path(
   post,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upload/upload_saved_scene_media_file_handler.rs

@@ -67,6 +67,13 @@ pub struct UploadSavedSceneMediaFileSuccessResponse {
   pub media_file_token: MediaFileToken,
 }
 
+/// Use this endpoint to make changes to an existing scene.
+///
+/// If you have a media token for the scene you're trying to save (i.e. not a completely
+/// new, unsaved scene), call this endpoint to overwrite and save the changes to the scene.
+///
+/// If you want to create a new copy of an existing scene, call the "new scene" endpoint
+/// instead as it won't overwrite an existing scene and will return a brand new media token.
 #[utoipa::path(
   post,
   tag = "Media Files",

crates/service/web/storyteller_web/src/http_server/endpoints/media_files/upsert_upload/write_scene_file/write_scene_file_media_file_handler.rs

@@ -39,6 +39,7 @@ pub struct WriteSceneFileMediaSuccessResponse {
   pub media_file_token: MediaFileToken,
 }
 
+/// DEPRECATED: Use the "new scene" and "saved scene" endpoints instead.
 #[deprecated]
 #[utoipa::path(
   post,