[Bf-blender-cvs] [6f41feb] master: Cleanup: BLO: move func doc comments to definitions of functions.

Bastien Montagne noreply at git.blender.org
Mon Oct 12 14:33:12 CEST 2015


Commit: 6f41febff17f80485485a4dbadf483617f3901be
Author: Bastien Montagne
Date:   Mon Oct 12 14:21:34 2015 +0200
Branches: master
https://developer.blender.org/rB6f41febff17f80485485a4dbadf483617f3901be

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

Follows our conventions and makes include file itself much cleaner.

===================================================================

M	source/blender/blenloader/BLO_readfile.h
M	source/blender/blenloader/intern/readblenentry.c
M	source/blender/blenloader/intern/readfile.c

===================================================================

diff --git a/source/blender/blenloader/BLO_readfile.h b/source/blender/blenloader/BLO_readfile.h
index 1ab83a5..44c6d27 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 6132a09..cd6df35 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.
+ * \re

@@ Diff output truncated at 10240 characters. @@




More information about the Bf-blender-cvs mailing list