1 files changed, 46 insertions, 0 deletions

diff --git a/source/blender/editors/space_file/filelist.h b/source/blender/editors/space_file/filelist.h
index e7cda106224..0119a9b4f52 100644
--- a/source/blender/editors/space_file/filelist.h
+++ b/source/blender/editors/space_file/filelist.h
@@ -51,6 +51,7 @@ typedef enum FileCheckType {
   CHECK_ALL = 3,
 } FileCheckType;
 
+/* not listbase itself */
 void folderlist_free(struct ListBase *folderlist);
 void folderlist_popdir(struct ListBase *folderlist, char *dir);
 void folderlist_pushdir(struct ListBase *folderlist, const char *dir);
@@ -73,13 +74,25 @@ void filelist_setfilter_options(struct FileList *filelist,
                                 const bool filter_assets_only,
                                 const char *filter_glob,
                                 const char *filter_search);
+/**
+ * Set the indexer to be used by the filelist.
+ *
+ * The given indexer allocation should be handled by the caller or defined statically.
+ */
 void filelist_setindexer(struct FileList *filelist, const struct FileIndexerType *indexer);
+/**
+ * \param catalog_id: The catalog that should be filtered by if \a catalog_visibility is
+ * #FILE_SHOW_ASSETS_FROM_CATALOG. May be NULL otherwise.
+ */
 void filelist_set_asset_catalog_filter_options(
     struct FileList *filelist,
     eFileSel_Params_AssetCatalogVisibility catalog_visibility,
     const struct bUUID *catalog_id);
 void filelist_tag_needs_filtering(struct FileList *filelist);
 void filelist_filter(struct FileList *filelist);
+/**
+ * \param asset_library_ref: May be NULL to unset the library.
+ */
 void filelist_setlibrary(struct FileList *filelist,
                          const struct AssetLibraryReference *asset_library_ref);
 
@@ -98,24 +111,51 @@ void filelist_clear_ex(struct FileList *filelist,
                        const bool do_asset_library,
                        const bool do_cache,
                        const bool do_selection);
+/**
+ * A "smarter" version of #filelist_clear() that calls partial clearing based on the filelist
+ * force-reset flags.
+ */
 void filelist_clear_from_reset_tag(struct FileList *filelist);
 void filelist_free(struct FileList *filelist);
 
 const char *filelist_dir(struct FileList *filelist);
 bool filelist_is_dir(struct FileList *filelist, const char *path);
+/**
+ * May modify in place given r_dir, which is expected to be FILE_MAX_LIBEXTRA length.
+ */
 void filelist_setdir(struct FileList *filelist, char *r_dir);
 
+/**
+ * Limited version of full update done by space_file's file_refresh(),
+ * to be used by operators and such.
+ * Ensures given filelist is ready to be used (i.e. it is filtered and sorted),
+ * unless it is tagged for a full refresh.
+ */
 int filelist_files_ensure(struct FileList *filelist);
 int filelist_needs_reading(struct FileList *filelist);
 FileDirEntry *filelist_file(struct FileList *filelist, int index);
 FileDirEntry *filelist_file_ex(struct FileList *filelist, int index, bool use_request);
 
+/**
+ * Find a file from a file name, or more precisely, its file-list relative path, inside the
+ * filtered items. \return The index of the found file or -1.
+ */
 int filelist_file_find_path(struct FileList *filelist, const char *file);
+/**
+ * Find a file representing \a id.
+ * \return The index of the found file or -1.
+ */
 int filelist_file_find_id(const struct FileList *filelist, const struct ID *id);
+/**
+ * Get the ID a file represents (if any). For #FILE_MAIN, #FILE_MAIN_ASSET.
+ */
 struct ID *filelist_file_get_id(const struct FileDirEntry *file);
 bool filelist_uid_is_set(const FileUID uid);
 void filelist_uid_unset(FileUID *r_uid);
 void filelist_file_cache_slidingwindow_set(struct FileList *filelist, size_t window_size);
+/**
+ * Load in cache all entries "around" given index (as much as block cache may hold).
+ */
 bool filelist_file_cache_block(struct FileList *filelist, const int index);
 
 bool filelist_needs_force_reset(struct FileList *filelist);
@@ -147,6 +187,9 @@ unsigned int filelist_entry_select_index_get(struct FileList *filelist,
                                              const int index,
                                              FileCheckType check);
 bool filelist_entry_is_selected(struct FileList *filelist, const int index);
+/**
+ * Set selection of the '..' parent entry, but only if it's actually visible.
+ */
 void filelist_entry_parent_select_set(struct FileList *filelist,
                                       FileSelType select,
                                       unsigned int flag,
@@ -157,6 +200,9 @@ void filelist_setrecursion(struct FileList *filelist, const int recursion_level)
 struct AssetLibrary *filelist_asset_library(struct FileList *filelist);
 
 struct BlendHandle *filelist_lib(struct FileList *filelist);
+/**
+ * \param dir: Must be #FILE_MAX_LIBEXTRA long!
+ */
 bool filelist_islibrary(struct FileList *filelist, char *dir, char **r_group);
 void filelist_freelib(struct FileList *filelist);