Cleanup: BLO: move func doc comments to definitions of functions.

Follows our conventions and makes include file itself much cleaner.

3 files changed, 159 insertions, 182 deletions

diff --git a/source/blender/blenloader/BLO_readfile.h b/source/blender/blenloader/BLO_readfile.h
index 1ab83a503ec..44c6d270cf5 100644
--- a/source/blender/blenloader/BLO_readfile.h
+++ b/source/blender/blenloader/BLO_readfile.h
@@ -70,183 +70,35 @@ typedef struct BlendFileData {
 	BlenFileType type;
 } BlendFileData;
 
-/**
- * Open a blender file from a pathname. The function
- * returns NULL and sets a report in the list if
- * it cannot open the file.
- *
- * \param filepath The path of the file to open.
- * \param reports If the return value is NULL, errors
- * indicating the cause of the failure.
- * \return The data of the file.
- */
-BlendFileData *BLO_read_from_file(
-        const char *filepath,
-        struct ReportList *reports);
-
-/**
- * Open a blender file from memory. The function
- * returns NULL and sets a report in the list if
- * it cannot open the file.
- *
- * \param mem The file data.
- * \param memsize The length of \a mem.
- * \param reports If the return value is NULL, errors
- * indicating the cause of the failure.
- * \return The data of the file.
- */
-BlendFileData *BLO_read_from_memory(
-        const void *mem, int memsize,
-        struct ReportList *reports);
-
-/**
- * oldmain is old main, from which we will keep libraries, images, ..
- * file name is current file, only for retrieving library data */
-
+BlendFileData *BLO_read_from_file(const char *filepath, struct ReportList *reports);
+BlendFileData *BLO_read_from_memory(const void *mem, int memsize, struct ReportList *reports);
 BlendFileData *BLO_read_from_memfile(
         struct Main *oldmain, const char *filename, struct MemFile *memfile,
         struct ReportList *reports);
 
-/**
- * Free's a BlendFileData structure and _all_ the
- * data associated with it (the userdef data, and
- * the main libblock data).
- *
- * \param bfd The structure to free.
- */
-void
-BLO_blendfiledata_free(BlendFileData *bfd);
-
-/**
- * Open a blendhandle from a file path.
- *
- * \param filepath: The file path to open.
- * \param reports: Report errors in opening the file (can be NULL).
- * \return A handle on success, or NULL on failure.
- */
-BlendHandle *BLO_blendhandle_from_file(
-        const char *filepath,
-        struct ReportList *reports);
-
-/**
- * Open a blendhandle from memory.
- *
- * \param mem The data to load from.
- * \param memsize The size of the data.
- * \return A handle on success, or NULL on failure.
- */
-
-BlendHandle *BLO_blendhandle_from_memory(
-        const void *mem, int memsize);
-
-/**
- * Gets the names of all the datablocks in a file
- * of a certain type (ie. All the scene names in
- * a file).
- *
- * \param bh The blendhandle to access.
- * \param ofblocktype The type of names to get.
- * \param tot_names The length of the returned list.
- * \return A BLI_linklist of strings. The string links
- * should be freed with malloc.
- */
-struct LinkNode *BLO_blendhandle_get_datablock_names(
-        BlendHandle *bh,
-        int ofblocktype, int *tot_names);
+void BLO_blendfiledata_free(BlendFileData *bfd);
 
-/**
- * Gets the previews of all the datablocks in a file
- * of a certain type (ie. All the scene names in
- * a file).
- *
- * \param bh The blendhandle to access.
- * \param ofblocktype The type of names to get.
- * \param tot_prev The length of the returned list.
- * \return A BLI_linklist of PreviewImage. The PreviewImage links
- * should be freed with malloc.
- */
-struct LinkNode *BLO_blendhandle_get_previews(
-        BlendHandle *bh,
-        int ofblocktype, int *tot_prev);
+BlendHandle *BLO_blendhandle_from_file(const char *filepath, struct ReportList *reports);
+BlendHandle *BLO_blendhandle_from_memory(const void *mem, int memsize);
 
-/**
- * Gets the names of all the datablock groups in a
- * file. (ie. file contains Scene, Mesh, and Lamp
- * datablocks).
- *
- * \param bh The blendhandle to access.
- * \return A BLI_linklist of strings. The string links
- * should be freed with malloc.
- */
+struct LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh, int ofblocktype, int *tot_names);
+struct LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *tot_prev);
 struct LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh);
 
-/**
- * Close and free a blendhandle. The handle
- * becomes invalid after this call.
- *
- * \param bh The handle to close.
- */
-void
-BLO_blendhandle_close(BlendHandle *bh);
+void BLO_blendhandle_close(BlendHandle *bh);
 
 /***/
 
 #define BLO_GROUP_MAX 32
 
 bool BLO_has_bfile_extension(const char *str);
-
-/**
- * \param path the full path to explode.
- * \param r_dir the string that'll contain path up to blend file itself ('library' path).
- * \param r_group the string that'll contain 'group' part of the path, if any. May be NULL.
- * \param r_name the string that'll contain data's name part of the path, if any. May be NULL.
- * \return true if path contains a blend file.
- */
 bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, char **r_name);
 
-
-/**
- * Initialize the BlendHandle for appending or linking library data.
- *
- * \param mainvar The current main database eg G.main or CTX_data_main(C).
- * \param bh A blender file handle as returned by BLO_blendhandle_from_file or BLO_blendhandle_from_memory.
- * \param filepath Used for relative linking, copied to the lib->name
- * \return the library Main, to be passed to BLO_library_append_named_part as mainl.
- */
-struct Main *BLO_library_link_begin(
-        struct Main *mainvar, BlendHandle **bh,
-        const char *filepath);
-
-
-/**
- * Link a named datablock from an external blend file.
- *
- * \param mainl The main database to link from (not the active one).
- * \param bh The blender file handle.
- * \param idname The name of the datablock (without the 2 char ID prefix)
- * \param idcode The kind of datablock to link.
- * \return the appended ID when found.
- */
-struct ID *BLO_library_link_named_part(
-        struct Main *mainl, BlendHandle **bh,
-        const char *idname, const int idcode);
-
-/**
- * Link a named datablock from an external blend file.
- * optionally instantiate the object/group in the scene when the flags are set.
- *
- * \param C The context, when NULL instancing object in the scene isn't done.
- * \param mainl The main database to link from (not the active one).
- * \param bh The blender file handle.
- * \param idname The name of the datablock (without the 2 char ID prefix)
- * \param idcode The kind of datablock to link.
- * \param flag Options for linking, used for instancing.
- * \return the appended ID when found.
- */
+struct Main *BLO_library_link_begin(struct Main *mainvar, BlendHandle **bh, const char *filepath);
+struct ID *BLO_library_link_named_part(struct Main *mainl, BlendHandle **bh, const char *idname, const int idcode);
 struct ID *BLO_library_link_named_part_ex(
         const struct bContext *C, struct Main *mainl, BlendHandle **bh,
         const char *idname, const int idcode, const short flag);
-
 void BLO_library_link_end(const struct bContext *C, struct Main *mainl, BlendHandle **bh, int idcode, short flag);
 
 void BLO_library_link_all(struct Main *mainl, BlendHandle *bh);
@@ -258,34 +110,13 @@ BlendFileData *blo_read_blendafterruntime(int file, const char *name, int actual
 /* internal function but we need to expose it */
 void blo_lib_link_screen_restore(struct Main *newmain, struct bScreen *curscreen, struct Scene *curscene);
 
-/**
- * BLO_expand_main() loops over all ID data in Main to mark relations.
- * Set (id->flag & LIB_NEED_EXPAND) to mark expanding. Flags get cleared after expanding.
- *
- * \param expand_doit_func() gets called for each ID block it finds
- */
 void BLO_main_expander(void (*expand_doit_func)(void *, struct Main *, void *));
-
-/**
- * BLO_expand_main() loops over all ID data in Main to mark relations.
- * Set (id->flag & LIB_NEED_EXPAND) to mark expanding. Flags get cleared after expanding.
- *
- * \param fdhandle usually filedata, or own handle
- * \param mainvar the Main database to expand
- */
 void BLO_expand_main(void *fdhandle, struct Main *mainvar);
 
 /* Update defaults in startup.blend & userprefs.blend, without having to save and embed it */
 void BLO_update_defaults_userpref_blend(void);
 void BLO_update_defaults_startup_blend(struct Main *mainvar);
 
-/**
- * Does a very light reading of given .blend file to extract its stored thumbnail.
- *
- * \param filepath The path of the file to extract thumbnail from.
- * \return The raw thumbnail
- *         (MEM-allocated, as stored in file, use BKE_main_thumbnail_to_imbuf() to convert it to ImBuf image).
- */
 struct BlendThumbnail *BLO_thumbnail_from_file(const char *filepath);
 
 #ifdef __cplusplus
diff --git a/source/blender/blenloader/intern/readblenentry.c b/source/blender/blenloader/intern/readblenentry.c
index 6132a091116..cd6df354ca7 100644
--- a/source/blender/blenloader/intern/readblenentry.c
+++ b/source/blender/blenloader/intern/readblenentry.c
@@ -72,6 +72,13 @@ void BLO_blendhandle_print_sizes(BlendHandle *, void *);
 
 /* Access routines used by filesel. */
 	 
+/**
+ * Open a blendhandle from a file path.
+ *
+ * \param filepath The file path to open.
+ * \param reports Report errors in opening the file (can be NULL).
+ * \return A handle on success, or NULL on failure.
+ */
 BlendHandle *BLO_blendhandle_from_file(const char *filepath, ReportList *reports)
 {
 	BlendHandle *bh;
@@ -81,6 +88,13 @@ BlendHandle *BLO_blendhandle_from_file(const char *filepath, ReportList *reports
 	return bh;
 }
 
+/**
+ * Open a blendhandle from memory.
+ *
+ * \param mem The data to load from.
+ * \param memsize The size of the data.
+ * \return A handle on success, or NULL on failure.
+ */
 BlendHandle *BLO_blendhandle_from_memory(const void *mem, int memsize)
 {
 	BlendHandle *bh;
@@ -120,6 +134,14 @@ void BLO_blendhandle_print_sizes(BlendHandle *bh, void *fp)
 	fprintf(fp, "]\n");
 }
 
+/**
+ * Gets the names of all the datablocks in a file of a certain type (e.g. all the scene names in a file).
+ *
+ * \param bh The blendhandle to access.
+ * \param ofblocktype The type of names to get.
+ * \param tot_names The length of the returned list.
+ * \return A BLI_linklist of strings. The string links should be freed with malloc.
+ */
 LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh, int ofblocktype, int *tot_names)
 {
 	FileData *fd = (FileData *) bh;
@@ -142,6 +164,14 @@ LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh, int ofblocktype,
 	return names;
 }
 
+/**
+ * Gets the previews of all the datablocks in a file of a certain type (e.g. all the scene previews in a file).
+ *
+ * \param bh The blendhandle to access.
+ * \param ofblocktype The type of names to get.
+ * \param tot_prev The length of the returned list.
+ * \return A BLI_linklist of PreviewImage. The PreviewImage links should be freed with malloc.
+ */
 LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *tot_prev)
 {
 	FileData *fd = (FileData *) bh;
@@ -232,7 +262,13 @@ LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *to
 	return previews;
 }
 
-LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh) 
+/**
+ * Gets the names of all the linkable datablock types available in a file. (e.g. "Scene", "Mesh", "Lamp", etc.).
+ *
+ * \param bh The blendhandle to access.
+ * \return A BLI_linklist of strings. The string links should be freed with malloc.
+ */
+LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh)
 {
 	FileData *fd = (FileData *) bh;
 	GSet *gathered = BLI_gset_ptr_new("linkable_groups gh");
@@ -260,6 +296,11 @@ LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh)
 	return names;
 }		
 
+/**
+ * Close and free a blendhandle. The handle becomes invalid after this call.
+ *
+ * \param bh The handle to close.
+ */
 void BLO_blendhandle_close(BlendHandle *bh)
 {
 	FileData *fd = (FileData *) bh;
@@ -269,6 +310,14 @@ void BLO_blendhandle_close(BlendHandle *bh)
 
 /**********/
 
+/**
+ * Open a blender file from a pathname. The function returns NULL
+ * and sets a report in the list if it cannot open the file.
+ *
+ * \param filepath The path of the file to open.
+ * \param reports If the return value is NULL, errors indicating the cause of the failure.
+ * \return The data of the file.
+ */
 BlendFileData *BLO_read_from_file(const char *filepath, ReportList *reports)
 {
 	BlendFileData *bfd = NULL;
@@ -284,6 +333,15 @@ BlendFileData *BLO_read_from_file(const char *filepath, ReportList *reports)
 	return bfd;
 }
 
+/**
+ * Open a blender file from memory. The function returns NULL
+ * and sets a report in the list if it cannot open the file.
+ *
+ * \param mem The file data.
+ * \param memsize The length of \a mem.
+ * \param reports If the return value is NULL, errors indicating the cause of the failure.
+ * \return The data of the file.
+ */
 BlendFileData *BLO_read_from_memory(const void *mem, int memsize, ReportList *reports)
 {
 	BlendFileData *bfd = NULL;
@@ -299,6 +357,12 @@ BlendFileData *BLO_read_from_memory(const void *mem, int memsize, ReportList *re
 	return bfd;
 }
 
+/**
+ * Used for undo/redo, skips part of libraries reading (assuming their data are already loaded & valid).
+ *
+ * \param oldmain old main, from which we will keep libraries and other datablocks that should not have changed.
+ * \param filename current file, only for retrieving library data.
+ */
 BlendFileData *BLO_read_from_memfile(Main *oldmain, const char *filename, MemFile *memfile, ReportList *reports)
 {
 	BlendFileData *bfd = NULL;
@@ -384,6 +448,11 @@ BlendFileData *BLO_read_from_memfile(Main *oldmain, const char *filename, MemFil
 	return bfd;
 }
 
+/**
+ * Frees a BlendFileData structure and *all* the data associated with it (the userdef data, and the main libblock data).
+ *
+ * \param bfd The structure to free.
+ */
 void BLO_blendfiledata_free(BlendFileData *bfd)
 {
 	if (bfd->main) {
diff --git a/source/blender/blenloader/intern/readfile.c b/source/blender/blenloader/intern/readfile.c
index 835bd59fb31..b4965da345d 100644
--- a/source/blender/blenloader/intern/readfile.c
+++ b/source/blender/blenloader/intern/readfile.c
@@ -1299,12 +1299,27 @@ void blo_freefiledata(FileData *fd)
 
 /* ************ DIV ****************** */
 
+/**
+ * Check whether given path ends with a blend file compatible extension (.blend, .ble or .blend.gz).
+ *
+ * \param str The path to check.
+ * \return true is this path ends with a blender file extension.
+ */
 bool BLO_has_bfile_extension(const char *str)
 {
 	const char *ext_test[4] = {".blend", ".ble", ".blend.gz", NULL};
 	return BLI_testextensie_array(str, ext_test);
 }
 
+/**
+ * Try to explode given path into its 'library components' (i.e. a .blend file, id type/group, and datablock itself).
+ *
+ * \param path the full path to explode.
+ * \param r_dir the string that'll contain path up to blend file itself ('library' path).
+ * \param r_group the string that'll contain 'group' part of the path, if any. May be NULL.
+ * \param r_name the string that'll contain data's name part of the path, if any. May be NULL.
+ * \return true if path contains a blend file.
+ */
 bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, char **r_name)
 {
 	/* We might get some data names with slashes, so we have to go up in path until we find blend file itself,
@@ -1361,6 +1376,13 @@ bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, cha
 	return true;
 }
 
+/**
+ * Does a very light reading of given .blend file to extract its stored thumbnail.
+ *
+ * \param filepath The path of the file to extract thumbnail from.
+ * \return The raw thumbnail
+ *         (MEM-allocated, as stored in file, use BKE_main_thumbnail_to_imbuf() to convert it to ImBuf image).
+ */
 BlendThumbnail *BLO_thumbnail_from_file(const char *filepath)
 {
 	FileData *fd;
@@ -9377,11 +9399,23 @@ static void expand_gpencil(FileData *fd, Main *mainvar, bGPdata *gpd)
 		expand_animdata(fd, mainvar, gpd->adt);
 }
 
+/**
+ * Set the callback func used over all ID data found by \a BLO_expand_main func.
+ *
+ * \param expand_doit_func Called for each ID block it finds.
+ */
 void BLO_main_expander(void (*expand_doit_func)(void *, Main *, void *))
 {
 	expand_doit = expand_doit_func;
 }
 
+/**
+ * Loop over all ID data in Main to mark relations.
+ * Set (id->flag & LIB_NEED_EXPAND) to mark expanding. Flags get cleared after expanding.
+ *
+ * \param fdhandle usually filedata, or own handle.
+ * \param mainvar the Main database to expand.
+ */
 void BLO_expand_main(void *fdhandle, Main *mainvar)
 {
 	ListBase *lbarray[MAX_LIBARRAY];
@@ -9637,7 +9671,9 @@ static ID *link_named_part(Main *mainl, FileData *fd, const char *idname, const
 	return id;
 }
 
-/* simple reader for copy/paste buffers */
+/**
+ * Simple reader for copy/paste buffers.
+ */
 void BLO_library_link_all(Main *mainl, BlendHandle *bh)
 {
 	FileData *fd = (FileData *)(bh);
@@ -9701,13 +9737,36 @@ static ID *link_named_part_ex(const bContext *C, Main *mainl, FileData *fd, cons
 	return id;
 }
 
+/**
+ * Link a named datablock from an external blend file.
+ *
+ * \param mainl The main database to link from (not the active one).
+ * \param bh The blender file handle.
+ * \param idname The name of the datablock (without the 2 char ID prefix).
+ * \param idcode The kind of datablock to link.
+ * \return the appended ID when found.
+ */
 ID *BLO_library_link_named_part(Main *mainl, BlendHandle **bh, const char *idname, const int idcode)
 {
 	FileData *fd = (FileData*)(*bh);
 	return link_named_part(mainl, fd, idname, idcode);
 }
 
-ID *BLO_library_link_named_part_ex(const bContext *C, Main *mainl, BlendHandle **bh, const char *idname, const int idcode, const short flag)
+/**
+ * Link a named datablock from an external blend file.
+ * Optionally instantiate the object/group in the scene when the flags are set.
+ *
+ * \param C The context, when NULL instantiating object in the scene isn't done.
+ * \param mainl The main database to link from (not the active one).
+ * \param bh The blender file handle.
+ * \param idname The name of the datablock (without the 2 char ID prefix).
+ * \param idcode The kind of datablock to link.
+ * \param flag Options for linking, used for instantiating.
+ * \return the appended ID when found.
+ */
+ID *BLO_library_link_named_part_ex(
+        const bContext *C, Main *mainl, BlendHandle **bh,
+        const char *idname, const int idcode, const short flag)
 {
 	FileData *fd = (FileData*)(*bh);
 	return link_named_part_ex(C, mainl, fd, idname, idcode, flag);
@@ -9752,6 +9811,14 @@ static Main *library_link_begin(Main *mainvar, FileData **fd, const char *filepa
 	return mainl;
 }
 
+/**
+ * Initialize the BlendHandle for linking library data.
+ *
+ * \param mainvar The current main database, e.g. G.main or CTX_data_main(C).
+ * \param bh A blender file handle as returned by \a BLO_blendhandle_from_file or \a BLO_blendhandle_from_memory.
+ * \param filepath Used for relative linking, copied to the \a lib->name.
+ * \return the library Main, to be passed to \a BLO_library_append_named_part as \a mainl.
+ */
 Main *BLO_library_link_begin(Main *mainvar, BlendHandle **bh, const char *filepath)
 {
 	FileData *fd = (FileData*)(*bh);
@@ -9830,6 +9897,16 @@ static void library_link_end(const bContext *C, Main *mainl, FileData **fd, int
 	}
 }
 
+/**
+ * Finalize the linking process (among other things, ensures remaining needed intantiation is done).
+ * \note Do not use \a bh after calling this function, it may frees it.
+ *
+ * \param C The context, when NULL instantiating object in the scene isn't done.
+ * \param mainl The main database to link from (not the active one).
+ * \param bh The blender file handle.
+ * \param idcode The kind of datablock that has been linked.
+ * \param flag Options for for instantiating.
+ */
 void BLO_library_link_end(const bContext *C, struct Main *mainl, BlendHandle **bh, int idcode, short flag)
 {
 	FileData *fd = (FileData*)(*bh);