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

Follows our conventions and makes include file itself much cleaner.

1 files changed, 70 insertions, 1 deletions

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) {