Cleanup: comments (long lines) in blenlib
authorCampbell Barton <ideasman42@gmail.com>
Sun, 21 Apr 2019 14:54:27 +0000 (00:54 +1000)
committerCampbell Barton <ideasman42@gmail.com>
Sun, 21 Apr 2019 20:30:08 +0000 (06:30 +1000)
33 files changed:
source/blender/blenlib/BLI_astar.h
source/blender/blenlib/BLI_dlrbTree.h
source/blender/blenlib/BLI_math_base.h
source/blender/blenlib/BLI_mempool.h
source/blender/blenlib/BLI_utildefines.h
source/blender/blenlib/PIL_time_utildefines.h
source/blender/blenlib/intern/BLI_ghash.c
source/blender/blenlib/intern/BLI_kdopbvh.c
source/blender/blenlib/intern/BLI_linklist_lockfree.c
source/blender/blenlib/intern/BLI_mempool.c
source/blender/blenlib/intern/array_store.c
source/blender/blenlib/intern/array_utils.c
source/blender/blenlib/intern/astar.c
source/blender/blenlib/intern/freetypefont.c
source/blender/blenlib/intern/hash_md5.c
source/blender/blenlib/intern/hash_mm2a.c
source/blender/blenlib/intern/kdtree_impl.h
source/blender/blenlib/intern/listbase.c
source/blender/blenlib/intern/math_base_inline.c
source/blender/blenlib/intern/math_color.c
source/blender/blenlib/intern/math_color_inline.c
source/blender/blenlib/intern/math_geom.c
source/blender/blenlib/intern/math_interp.c
source/blender/blenlib/intern/math_matrix.c
source/blender/blenlib/intern/math_solvers.c
source/blender/blenlib/intern/math_statistics.c
source/blender/blenlib/intern/path_util.c
source/blender/blenlib/intern/polyfill_2d_beautify.c
source/blender/blenlib/intern/rct.c
source/blender/blenlib/intern/smallhash.c
source/blender/blenlib/intern/string.c
source/blender/blenlib/intern/string_utils.c
source/blender/blenlib/intern/task.c

index 320c450..3fe37d7 100644 (file)
@@ -88,8 +88,10 @@ void BLI_astar_solution_clear(BLI_AStarSolution *as_solution);
 void BLI_astar_solution_free(BLI_AStarSolution *as_solution);
 
 /**
- * Callback computing the current cost (distance) to next node, and the estimated overall cost to destination node
- * (A* expects this estimation to always be less or equal than actual shortest path from next node to destination one).
+ * Callback computing the current cost (distance) to next node,
+ * and the estimated overall cost to destination node
+ * (A* expects this estimation to always be less or equal than actual shortest path
+ * from next node to destination one).
  *
  * \param link: the graph link between current node and next one.
  * \param node_idx_curr: current node index.
index 222cdea..11e5e2c 100644 (file)
@@ -68,20 +68,23 @@ typedef struct DLRBT_Tree {
 
 /* Callback Types --------------------------------- */
 
-/* return -1, 0, 1 for whether the given data is less than, equal to, or greater than the given node
+/* Return -1, 0, 1 for whether the given data is less than,
+ * equal to, or greater than the given node.
  * - node: <DLRBT_Node> the node to compare to
- * - data: pointer to the relevant data or values stored in the bitpattern dependent on the function
+ * - data: pointer to the relevant data or values stored in the bitpattern
+ *   dependent on the function.
  */
 typedef short (*DLRBT_Comparator_FP)(void *node, void *data);
 
-/* return a new node instance wrapping the given data
- * - data: pointer to the relevant data to create a subclass of node from
+/* Return a new node instance wrapping the given data
+ * - data: Pointer to the relevant data to create a subclass of node from
  */
 typedef DLRBT_Node *(*DLRBT_NAlloc_FP)(void *data);
 
-/* update an existing node instance accordingly to be in sync with the given data *
- * - node: <DLRBT_Node> the node to update
- * - data: pointer to the relevant data or values stored in the bitpattern dependent on the function
+/* Update an existing node instance accordingly to be in sync with the given data *
+ * - node: <DLRBT_Node> the node to update.
+ * - data: Pointer to the relevant data or values stored in the bitpattern
+ *   dependent on the function.
  */
 typedef void (*DLRBT_NUpdate_FP)(void *node, void *data);
 
index aff0162..177a1a8 100644 (file)
@@ -200,8 +200,9 @@ double double_round(double x, int ndigits);
 /** \note 0.0001 is too small becaues normals may be converted from short's: see T34322. */
 #  define BLI_ASSERT_UNIT_EPSILON 0.0002f
 /**
- * \note Checks are flipped so NAN doesn't assert. This is done because we're making sure the value was normalized
- * and in the case we don't want NAN to be raising asserts since there is nothing to be done in that case.
+ * \note Checks are flipped so NAN doesn't assert.
+ * This is done because we're making sure the value was normalized and in the case we
+ * don't want NAN to be raising asserts since there is nothing to be done in that case.
  */
 #  define BLI_ASSERT_UNIT_V3(v) \
     { \
index fca3d26..67851a6 100644 (file)
@@ -77,8 +77,10 @@ enum {
   BLI_MEMPOOL_NOP = 0,
   /** allow iterating on this mempool.
    *
-   * \note this requires that the first four bytes of the elements never begin with 'free' (FREEWORD).
-   * \note order of iteration is only assured to be the order of allocation when no chunks have been freed.
+   * \note this requires that the first four bytes of the elements
+   * never begin with 'free' (#FREEWORD).
+   * \note order of iteration is only assured to be the
+   * order of allocation when no chunks have been freed.
    */
   BLI_MEMPOOL_ALLOW_ITER = (1 << 0),
 };
index 970c64e..216e409 100644 (file)
@@ -703,7 +703,8 @@ extern bool BLI_memory_is_zero(const void *arr, const size_t arr_size);
  *     args = [(chr(ord('a') + (c % 26)) + (chr(ord('0') + (c // 26)))) for c in range(i + 1)]
  *     print("#define _VA_UNUSED_VARS_%d(%s) \\" % (i + 1, ", ".join(args)))
  *     print("\t((void)(%s)%s)" %
- *             (args[0], ((", _VA_UNUSED_VARS_" + str(i) + "(%s)") if i else "%s") % ", ".join((args[1:]))))
+ *             (args[0], ((", _VA_UNUSED_VARS_" + str(i) + "(%s)") if i else "%s") %
+ *              ", ".join((args[1:]))))
  * \endcode
  */
 
index cfdea54..198b6d1 100644 (file)
@@ -62,8 +62,9 @@
   (void)0
 
 /**
- * _AVERAGED variants do same thing as their basic counterpart, but additionally add elapsed time to an averaged
- * static value, useful to get sensible timing of code running fast and often.
+ * _AVERAGED variants do same thing as their basic counterpart,
+ * but additionally add elapsed time to an averaged static value,
+ * useful to get sensible timing of code running fast and often.
  */
 #define TIMEIT_START_AVERAGED(var) \
   { \
index c0ec1eb..769bb02 100644 (file)
@@ -73,7 +73,8 @@ BLI_STATIC_ASSERT(ARRAY_SIZE(hashsizes) == GHASH_MAX_SIZE, "Invalid 'hashsizes'
 /**
  * \note Max load #GHASH_LIMIT_GROW used to be 3. (pre 2.74).
  * Python uses 0.6666, tommyhashlib even goes down to 0.5.
- * Reducing our from 3 to 0.75 gives huge speedup (about twice quicker pure GHash insertions/lookup,
+ * Reducing our from 3 to 0.75 gives huge speedup
+ * (about twice quicker pure GHash insertions/lookup,
  * about 25% - 30% quicker 'dynamic-topology' stroke drawing e.g.).
  * Min load #GHASH_LIMIT_SHRINK is a quarter of max load, to avoid resizing to quickly.
  */
@@ -379,7 +380,8 @@ BLI_INLINE void ghash_buckets_reset(GHash *gh, const uint nentries)
 
 /**
  * Internal lookup function.
- * Takes hash and bucket_index arguments to avoid calling #ghash_keyhash and #ghash_bucket_index multiple times.
+ * Takes hash and bucket_index arguments to avoid calling #ghash_keyhash and #ghash_bucket_index
+ * multiple times.
  */
 BLI_INLINE Entry *ghash_lookup_entry_ex(GHash *gh, const void *key, const uint bucket_index)
 {
@@ -397,7 +399,8 @@ BLI_INLINE Entry *ghash_lookup_entry_ex(GHash *gh, const void *key, const uint b
 
 /**
  * Internal lookup function, returns previous entry of target one too.
- * Takes bucket_index argument to avoid calling #ghash_keyhash and #ghash_bucket_index multiple times.
+ * Takes bucket_index argument to avoid calling #ghash_keyhash and #ghash_bucket_index
+ * multiple times.
  * Useful when modifying buckets somehow (like removing an entry...).
  */
 BLI_INLINE Entry *ghash_lookup_entry_prev_ex(GHash *gh,
@@ -451,7 +454,8 @@ static GHash *ghash_new(GHashHashFP hashfp,
 
 /**
  * Internal insert function.
- * Takes hash and bucket_index arguments to avoid calling #ghash_keyhash and #ghash_bucket_index multiple times.
+ * Takes hash and bucket_index arguments to avoid calling #ghash_keyhash and #ghash_bucket_index
+ * multiple times.
  */
 BLI_INLINE void ghash_insert_ex(GHash *gh, void *key, void *val, const uint bucket_index)
 {
@@ -723,7 +727,8 @@ GHash *BLI_ghash_new(GHashHashFP hashfp, GHashCmpFP cmpfp, const char *info)
 }
 
 /**
- * Copy given GHash. Keys and values are also copied if relevant callback is provided, else pointers remain the same.
+ * Copy given GHash. Keys and values are also copied if relevant callback is provided,
+ * else pointers remain the same.
  */
 GHash *BLI_ghash_copy(GHash *gh, GHashKeyCopyFP keycopyfp, GHashValCopyFP valcopyfp)
 {
@@ -951,7 +956,8 @@ bool BLI_ghash_haskey(GHash *gh, const void *key)
 }
 
 /**
- * Remove a random entry from \a gh, returning true if a key/value pair could be removed, false otherwise.
+ * Remove a random entry from \a gh, returning true
+ * if a key/value pair could be removed, false otherwise.
  *
  * \param r_key: The removed key.
  * \param r_val: The removed value.
@@ -1332,7 +1338,8 @@ int BLI_gset_buckets_len(GSet *gs)
 
 /**
  * Measure how well the hash function performs (1.0 is approx as good as random distribution),
- * and return a few other stats like load, variance of the distribution of the entries in the buckets, etc.
+ * and return a few other stats like load,
+ * variance of the distribution of the entries in the buckets, etc.
  *
  * Smaller is better!
  */
index 22e64d6..98e8a5e 100644 (file)
@@ -622,9 +622,12 @@ static int implicit_leafs_index(const BVHBuildHelper *data, const int depth, con
 /**
  * Generalized implicit tree build
  *
- * An implicit tree is a tree where its structure is implied, thus there is no need to store child pointers or indexs.
- * Its possible to find the position of the child or the parent with simple maths (multiplication and adittion).
- * This type of tree is for example used on heaps.. where node N has its childs at indexs N*2 and N*2+1.
+ * An implicit tree is a tree where its structure is implied,
+ * thus there is no need to store child pointers or indexs.
+ * Its possible to find the position of the child or the parent with simple maths
+ * (multiplication and adittion).
+ * This type of tree is for example used on heaps..
+ * where node N has its childs at indexs N*2 and N*2+1.
  *
  * Although in this case the tree type is general.. and not know until runtime.
  * tree_type stands for the maximum number of childs that a tree node can have.
@@ -766,14 +769,16 @@ static void non_recursive_bvh_div_nodes_task_cb(void *__restrict userdata,
  * - At most only one branch will have NULL childs;
  * - All leafs will be stored at level N or N+1.
  *
- * This function creates an implicit tree on branches_array, the leafs are given on the leafs_array.
+ * This function creates an implicit tree on branches_array,
+ * the leafs are given on the leafs_array.
  *
  * The tree is built per depth levels. First branches at depth 1.. then branches at depth 2.. etc..
- * The reason is that we can build level N+1 from level N without any data dependencies.. thus it allows
- * to use multithread building.
+ * The reason is that we can build level N+1 from level N without any data dependencies..
+ * thus it allows to use multithread building.
  *
- * To archive this is necessary to find how much leafs are accessible from a certain branch, BVHBuildHelper
- * #implicit_needed_branches and #implicit_leafs_index are auxiliary functions to solve that "optimal-split".
+ * To archive this is necessary to find how much leafs are accessible from a certain branch,
+ * #BVHBuildHelper, #implicit_needed_branches and #implicit_leafs_index
+ * are auxiliary functions to solve that "optimal-split".
  */
 static void non_recursive_bvh_div_nodes(const BVHTree *tree,
                                         BVHNode *branches_array,
@@ -1731,9 +1736,10 @@ float BLI_bvhtree_bb_raycast(const float bv[6],
  * Calls the callback for every ray intersection
  *
  * \note Using a \a callback which resets or never sets the #BVHTreeRayHit index & dist works too,
- * however using this function means existing generic callbacks can be used from custom callbacks without
- * having to handle resetting the hit beforehand.
- * It also avoid redundant argument and return value which aren't meaningful when collecting multiple hits.
+ * however using this function means existing generic callbacks can be used from custom callbacks
+ * without having to handle resetting the hit beforehand.
+ * It also avoid redundant argument and return value which aren't meaningful
+ * when collecting multiple hits.
  */
 void BLI_bvhtree_ray_cast_all_ex(BVHTree *tree,
                                  const float co[3],
@@ -1786,7 +1792,8 @@ void BLI_bvhtree_ray_cast_all(BVHTree *tree,
 /* -------------------------------------------------------------------- */
 /** \name BLI_bvhtree_range_query
  *
- * Allocs and fills an array with the indexs of node that are on the given spherical range (center, radius).
+ * Allocs and fills an array with the indexs of node that are on the given spherical range
+ * (center, radius).
  * Returns the size of the array.
  *
  * \{ */
@@ -2063,7 +2070,8 @@ typedef struct BVHTree_WalkData {
 } BVHTree_WalkData;
 
 /**
- * Runs first among nodes children of the first node before going to the next node in the same layer.
+ * Runs first among nodes children of the first node before going
+ * to the next node in the same layer.
  *
  * \return false to break out of the search early.
  */
index d27e65a..795e5ba 100644 (file)
@@ -57,10 +57,10 @@ void BLI_linklist_lockfree_insert(LockfreeLinkList *list, LockfreeLinkNode *node
 {
   /* Based on:
    *
-   *   John D. Valois
-   *   Implementing Lock-Free Queues
+   * John D. Valois
+   * Implementing Lock-Free Queues
    *
-   *   http://people.csail.mit.edu/bushl2/rpi/portfolio/lockfree-grape/documents/lock-free-linked-lists.pdf
+   * http://people.csail.mit.edu/bushl2/rpi/portfolio/lockfree-grape/documents/lock-free-linked-lists.pdf
    */
   bool keep_working;
   LockfreeLinkNode *tail_node;
index 4860fa6..5765540 100644 (file)
@@ -63,7 +63,8 @@
 
 /**
  * Important that this value is an is _not_  aligned with ``sizeof(void *)``.
- * So having a pointer to 2/4/8... aligned memory is enough to ensure the freeword will never be used.
+ * So having a pointer to 2/4/8... aligned memory is enough to ensure
+ * the freeword will never be used.
  * To be safe, use a word thats the same in both directions.
  */
 #define FREEWORD \
@@ -547,8 +548,10 @@ void BLI_mempool_iternew(BLI_mempool *pool, BLI_mempool_iter *iter)
 /**
  * Initialize an array of mempool iterators, #BLI_MEMPOOL_ALLOW_ITER flag must be set.
  *
- * This is used in threaded code, to generate as much iterators as needed (each task should have its own),
- * such that each iterator goes over its own single chunk, and only getting the next chunk to iterate over has to be
+ * This is used in threaded code, to generate as much iterators as needed
+ * (each task should have its own),
+ * such that each iterator goes over its own single chunk,
+ * and only getting the next chunk to iterate over has to be
  * protected against concurrency (which can be done in a lockless way).
  *
  * To be used when creating a task for each single item in the pool is totally overkill.
index 0e7b9a2..825f2e3 100644 (file)
  *
  * - BArrayStore: The whole array store.
  * - BArrayState: Represents a single state (array) of data.
- *   These can be add using a reference state, while this could be considered the previous or parent state.
- *   no relationship is kept, so the caller is free to add any state from the same BArrayStore as a reference.
+ *   These can be add using a reference state,
+ *   while this could be considered the previous or parent state.
+ *   no relationship is kept,
+ *   so the caller is free to add any state from the same BArrayStore as a reference.
  *
  * <pre>
  * <+> BArrayStore: root data-structure,
 
 /* For arrays of matching length, test that *enough* of the chunks are aligned,
  * and simply step over both arrays, using matching chunks.
- * This avoids overhead of using a lookup table for cases when we can assume they're mostly aligned.
+ * This avoids overhead of using a lookup table for cases
+ * when we can assume they're mostly aligned.
  */
 #define USE_ALIGN_CHUNKS_TEST
 
@@ -1411,7 +1414,8 @@ static BChunkList *bchunk_list_from_data_merge(const BArrayInfo *info,
  *   but adds overhead by increasing the number of chunks to look-up when searching for duplicates,
  *   as well as some overhead constructing the original array again, with more calls to ``memcpy``.
  * - Larger values reduce the *book keeping* overhead,
- *   but increase the chance a small, isolated change will cause a larger amount of data to be duplicated.
+ *   but increase the chance a small,
+ *   isolated change will cause a larger amount of data to be duplicated.
  *
  * \return A new array store, to be freed with #BLI_array_store_destroy.
  */
@@ -1542,7 +1546,8 @@ size_t BLI_array_store_calc_size_compacted_get(const BArrayStore *bs)
  * typically this is the previous state,
  * however it can be any previously created state from this \a bs.
  *
- * \return The new state, which is used by the caller as a handle to get back the contents of \a data.
+ * \return The new state,
+ * which is used by the caller as a handle to get back the contents of \a data.
  * This may be removed using #BLI_array_store_state_remove,
  * otherwise it will be removed with #BLI_array_store_destroy.
  */
index f941c05..25bcf71 100644 (file)
@@ -185,7 +185,8 @@ void _bli_array_binary_or(
  * \param use_wrap: Detect contiguous ranges across the first/last points.
  * In this case the second index of \a span_step may be lower than the first,
  * which indicates the values are wrapped.
- * \param use_delimit_bounds: When false, ranges that defined by the start/end indices are excluded.
+ * \param use_delimit_bounds: When false,
+ * ranges that defined by the start/end indices are excluded.
  * This option has no effect when \a use_wrap is enabled.
  * \param test_fn: Function to test if the item should be included in the range.
  * \param user_data: User data for \a test_fn.
index c275f67..c8f2160 100644 (file)
  * in addition to distance already walked. This heuristic allows more efficiency
  * in finding optimal path.
  *
- * Implementation based on Wikipedia A* page [https://en.wikipedia.org/wiki/A*_search_algorithm].
+ * Implementation based on Wikipedia A* page:
+ * https://en.wikipedia.org/wiki/A*_search_algorithm
  *
- * Note that most memory handling here is done through two different MemArena's. Those should also be used to allocate
+ * Note that most memory handling here is done through two different MemArena's.
+ * Those should also be used to allocate
  * custom data needed to a specific use of A*.
- * The first one, owned by BLI_AStarGraph, is for 'static' data that will live as long as the graph.
- * The second one, owned by BLI_AStarSolution, is for data used during a single path solve. It will be cleared
- * much more often than graph's one.
+ * The first one, owned by BLI_AStarGraph,
+ * is for 'static' data that will live as long as the graph.
+ * The second one, owned by BLI_AStarSolution, is for data used during a single path solve.
+ * It will be cleared much more often than graph's one.
  */
 
 #include <limits.h>
@@ -53,7 +56,8 @@
 /**
  * Init a node in A* graph.
  *
- * \param custom_data: an opaque pointer attached to this link, available e.g. to cost callback function.
+ * \param custom_data: an opaque pointer attached to this link,
+ * available e.g. to cost callback function.
  */
 void BLI_astar_node_init(BLI_AStarGraph *as_graph, const int node_index, void *custom_data)
 {
@@ -63,8 +67,10 @@ void BLI_astar_node_init(BLI_AStarGraph *as_graph, const int node_index, void *c
 /**
  * Add a link between two nodes of our A* graph.
  *
- * \param cost: the 'length' of the link (actual distance between two vertices or face centers e.g.).
- * \param custom_data: an opaque pointer attached to this link, available e.g. to cost callback function.
+ * \param cost: the 'length' of the link
+ * (actual distance between two vertices or face centers e.g.).
+ * \param custom_data: an opaque pointer attached to this link,
+ * available e.g. to cost callback function.
  */
 void BLI_astar_node_link_add(BLI_AStarGraph *as_graph,
                              const int node1_index,
@@ -98,7 +104,8 @@ int BLI_astar_node_link_other_node(BLI_AStarGNLink *lnk, const int idx)
 /**
  * Initialize a solution data for given A* graph. Does not compute anything!
  *
- * \param custom_data: an opaque pointer attached to this link, available e.g. to cost callback function.
+ * \param custom_data: an opaque pointer attached to this link, available e.g
+ * . to cost callback function.
  *
  * \note BLI_AStarSolution stores nearly all data needed during solution compute.
  */
@@ -165,7 +172,8 @@ void BLI_astar_solution_free(BLI_AStarSolution *as_solution)
  *
  * Nodes might be e.g. vertices, faces, ...
  *
- * \param custom_data: an opaque pointer attached to this link, available e.g. to cost callback function.
+ * \param custom_data: an opaque pointer attached to this link,
+ * available e.g. to cost callback function.
  */
 void BLI_astar_graph_init(BLI_AStarGraph *as_graph, const int node_num, void *custom_data)
 {
@@ -194,8 +202,9 @@ void BLI_astar_graph_free(BLI_AStarGraph *as_graph)
 /**
  * Solve a path in given graph, using given 'cost' callback function.
  *
- * \param max_steps: maximum number of nodes the found path may have. Useful in performance-critical usages.
- *                  If no path is found within given steps, returns false too.
+ * \param max_steps: maximum number of nodes the found path may have.
+ * Useful in performance-critical usages.
+ * If no path is found within given steps, returns false too.
  * \return true if a path was found, false otherwise.
  */
 bool BLI_astar_graph_solve(BLI_AStarGraph *as_graph,
index a8b8f01..92553ae 100644 (file)
@@ -497,7 +497,7 @@ VChar *BLI_vfontchar_copy(const VChar *vchar_src, const int UNUSED(flag))
   return vchar_dst;
 }
 
-/*
+/**
  * from: http://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html#section-1
  *
  * Vectorial representation of Freetype glyphs
@@ -508,27 +508,30 @@ VChar *BLI_vfontchar_copy(const VChar *vchar_src, const int UNUSED(flag))
  * they come from the TrueType format. The latter are called cubic arcs and mostly come from the
  * Type1 format.
  *
- * Each arc is described through a series of start, end and control points. Each point of the outline
- * has a specific tag which indicates whether it is used to describe a line segment or an arc.
+ * Each arc is described through a series of start, end and control points.
+ * Each point of the outline has a specific tag which indicates whether it is
+ * used to describe a line segment or an arc.
  * The following rules are applied to decompose the contour's points into segments and arcs :
  *
  * # two successive "on" points indicate a line segment joining them.
  *
- * # one conic "off" point amidst two "on" points indicates a conic bezier arc, the "off" point being
- *   the control point, and the "on" ones the start and end points.
+ * # one conic "off" point amidst two "on" points indicates a conic bezier arc,
+ *   the "off" point being the control point, and the "on" ones the start and end points.
  *
- * # Two successive cubic "off" points amidst two "on" points indicate a cubic bezier arc. There must
- *   be exactly two cubic control points and two on points for each cubic arc (using a single cubic
- *   "off" point between two "on" points is forbidden, for example).
+ * # Two successive cubic "off" points amidst two "on" points indicate a cubic bezier arc.
+ *   There must be exactly two cubic control points and two on points for each cubic arc
+ *   (using a single cubic "off" point between two "on" points is forbidden, for example).
  *
- * # finally, two successive conic "off" points forces the rasterizer to create (during the scan-line
- *   conversion process exclusively) a virtual "on" point amidst them, at their exact middle. This
- *   greatly facilitates the definition of successive conic bezier arcs. Moreover, it's the way
- *   outlines are described in the TrueType specification.
+ * # finally, two successive conic "off" points forces the rasterizer to create
+ *   (during the scan-line conversion process exclusively) a virtual "on" point amidst them,
+ *   at their exact middle.
+ *   This greatly facilitates the definition of successive conic bezier arcs.
+ *   Moreover, it's the way outlines are described in the TrueType specification.
  *
  * Note that it is possible to mix conic and cubic arcs in a single contour, even though no current
  * font driver produces such outlines.
  *
+ * <pre>
  *                                   *            # on
  *                                                * off
  *                                __---__
@@ -560,9 +563,11 @@ VChar *BLI_vfontchar_copy(const VChar *vchar_src, const int UNUSED(flag))
  *      Two "on" points
  *    and two "cubic" point
  *       between them
- * Each glyph's original outline points are located on a grid of indivisible units. The points are stored
- * in the font file as 16-bit integer grid coordinates, with the grid origin's being at (0, 0); they thus
- * range from -16384 to 16383.
+ * </pre>
+ *
+ * Each glyph's original outline points are located on a grid of indivisible units.
+ * The points are stored in the font file as 16-bit integer grid coordinates,
+ * with the grid origin's being at (0, 0); they thus range from -16384 to 16383.
  *
  * Convert conic to bezier arcs:
  * Conic P0 P1 P2
index d3ba5ee..44a9348 100644 (file)
@@ -49,8 +49,9 @@
 #endif
 
 /* If UINT_MAX isn't defined, assume it's a 32-bit type.
- * This should be valid for all systems GNU cares about because that doesn't include 16-bit systems,
- * and only modern systems (that certainly have <limits.h>) have 64+-bit integral types.
+ * This should be valid for all systems GNU cares about
+ * because that doesn't include 16-bit systems, and only modern systems
+ * (that certainly have <limits.h>) have 64+-bit integral types.
  */
 
 #ifndef UINT_MAX
@@ -359,9 +360,10 @@ int BLI_hash_md5_stream(FILE *stream, void *resblock)
   return 0;
 }
 
-/** Compute MD5 message digest for 'len' bytes beginning at 'buffer'.
- *  The result is always in little endian byte order, so that a byte-wise output yields to the wanted
- *  ASCII representation of the message digest.
+/**
+ * Compute MD5 message digest for 'len' bytes beginning at 'buffer'.
+ * The result is always in little endian byte order,
+ * so that a byte-wise output yields to the wanted ASCII representation of the message digest.
  */
 void *BLI_hash_md5_buffer(const char *buffer, size_t len, void *resblock)
 {
index ee4a632..32b6e1a 100644 (file)
  * A very fast hash generating int32 result, with few collisions and good repartition.
  *
  * See also:
- *     reference implementation: https://smhasher.googlecode.com/svn-history/r130/trunk/MurmurHash2.cpp
- *     and http://programmers.stackexchange.com/questions/49550/which-hashing-algorithm-is-best-for-uniqueness-and-speed
+ * reference implementation:
+ * - https://smhasher.googlecode.com/svn-history/r130/trunk/MurmurHash2.cpp
+ * - http://programmers.stackexchange.com/questions/49550/which-hashing-algorithm-is-best-for-uniqueness-and-speed
  *
- * \warning Do not store that hash in files or such, it is not endian-agnostic, so you should only use it
- *          for temporary data.
+ * \warning Do not store that hash in files or such, it is not endian-agnostic,
+ * so you should only use it for temporary data.
  */
 
 #include "BLI_compiler_attrs.h"
index a4b1833..32e8a4e 100644 (file)
@@ -58,7 +58,8 @@ struct KDTree {
 
 #define KD_NODE_UNSET ((uint)-1)
 
-/** When set we know all values are unbalanced, otherwise clear them when re-balancing: see T62210. */
+/** When set we know all values are unbalanced,
+ * otherwise clear them when re-balancing: see T62210. */
 #define KD_NODE_ROOT_IS_INIT ((uint)-2)
 
 /* -------------------------------------------------------------------- */
@@ -732,7 +733,8 @@ int BLI_kdtree_nd_(range_search)(const KDTree *tree,
  * A version of #BLI_kdtree_3d_range_search which runs a callback
  * instead of allocating an array.
  *
- * \param search_cb: Called for every node found in \a range, false return value performs an early exit.
+ * \param search_cb: Called for every node found in \a range,
+ * false return value performs an early exit.
  *
  * \note the order of calls isn't sorted based on distance.
  */
index ff9e213..31d3729 100644 (file)
@@ -224,7 +224,8 @@ void BLI_listbase_swaplinks(ListBase *listbase, void *vlinka, void *vlinkb)
 }
 
 /**
- * Swaps \a vlinka and \a vlinkb from their respective lists. Assumes they are both already in their lista!
+ * Swaps \a vlinka and \a vlinkb from their respective lists.
+ * Assumes they are both already in their lista!
  */
 void BLI_listbases_swaplinks(ListBase *listbasea, ListBase *listbaseb, void *vlinka, void *vlinkb)
 {
index f1ceaca..221a27f 100644 (file)
@@ -428,11 +428,13 @@ MINLINE int compare_ff(float a, float b, const float max_diff)
 }
 
 /**
- * Almost-equal for IEEE floats, using their integer representation (mixing ULP and absolute difference methods).
+ * Almost-equal for IEEE floats, using their integer representation
+ * (mixing ULP and absolute difference methods).
  *
  * \param max_diff: is the maximum absolute difference (allows to take care of the near-zero area,
- *                 where relative difference methods cannot really work).
- * \param max_ulps: is the 'maximum number of floats + 1' allowed between \a a and \a b to consider them equal.
+ * where relative difference methods cannot really work).
+ * \param max_ulps: is the 'maximum number of floats + 1'
+ * allowed between \a a and \a b to consider them equal.
  *
  * \see https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/
  */
index bc16994..f07c2ec 100644 (file)
@@ -355,11 +355,11 @@ void hsv_clamp_v(float hsv[3], float v_max)
 }
 
 /**
- * We define a 'cpack' here as a (3 byte color code) number that can be expressed like 0xFFAA66 or so.
- * for that reason it is sensitive for endianness... with this function it works correctly.
+ * We define a 'cpack' here as a (3 byte color code)
+ * number that can be expressed like 0xFFAA66 or so.
+ * For that reason it is sensitive for endianness... with this function it works correctly.
  * \see #imm_cpack
  */
-
 unsigned int hsv_to_cpack(float h, float s, float v)
 {
   unsigned int r, g, b;
index 1309eb1..d7a2d68 100644 (file)
@@ -265,8 +265,8 @@ MINLINE void cpack_cpy_3ub(unsigned char r_col[3], const unsigned int pack)
  *
  * \warning
  * These are only an approximation,
- * in almost _all_ cases, #IMB_colormanagement_get_luminance should be used instead.
- * however for screen-only colors which don't depend on the currently loaded profile - this is preferred.
+ * in almost _all_ cases, #IMB_colormanagement_get_luminance should be used instead. However for
+ * screen-only colors which don't depend on the currently loaded profile - this is preferred.
  * Checking theme colors for contrast, etc. Basically anything outside the render pipeline.
  *
  * \{ */
index 6683085..fa018cc 100644 (file)
@@ -599,7 +599,8 @@ float dist_squared_to_ray_v3_normalized(const float ray_origin[3],
 
 /**
  * Find the closest point in a seg to a ray and return the distance squared.
- * \param r_point: Is the point on segment closest to ray (or to ray_origin if the ray and the segment are parallel).
+ * \param r_point: Is the point on segment closest to ray
+ * (or to ray_origin if the ray and the segment are parallel).
  * \param r_depth: the distance of r_point projection on ray to the ray_origin.
  */
 float dist_squared_ray_to_seg_v3(const float ray_origin[3],
@@ -2868,7 +2869,8 @@ bool isect_ray_aabb_v3(const struct IsectRayAABB_Precalc *data,
  * Test a bounding box (AABB) for ray intersection.
  * Assumes the ray is already local to the boundbox space.
  *
- * \note: \a direction should be normalized if you intend to use the \a tmin or \a tmax distance results!
+ * \note: \a direction should be normalized
+ * if you intend to use the \a tmin or \a tmax distance results!
  */
 bool isect_ray_aabb_v3_simple(const float orig[3],
                               const float dir[3],
@@ -3131,7 +3133,8 @@ bool isect_point_tri_prism_v3(const float p[3],
 /**
  * \param r_isect_co: The point \a p projected onto the triangle.
  * \return True when \a p is inside the triangle.
- * \note Its up to the caller to check the distance between \a p and \a r_vi against an error margin.
+ * \note Its up to the caller to check the distance between \a p and \a r_vi
+ * against an error margin.
  */
 bool isect_point_tri_v3(
     const float p[3], const float v1[3], const float v2[3], const float v3[3], float r_isect_co[3])
@@ -3408,7 +3411,12 @@ void interp_weights_quad_v3(float w[4],
   }
 }
 
-/* return 1 of point is inside triangle, 2 if it's on the edge, 0 if point is outside of triangle */
+/**
+ * \return
+ * - 0 if the point is outside of triangle.
+ * - 1 if the point is inside triangle.
+ * - 2 if it's on the edge.
+ * */
 int barycentric_inside_triangle_v2(const float w[3])
 {
   if (IN_RANGE(w[0], 0.0f, 1.0f) && IN_RANGE(w[1], 0.0f, 1.0f) && IN_RANGE(w[2], 0.0f, 1.0f)) {
@@ -3469,7 +3477,8 @@ void barycentric_weights_v2(
 
 /**
  * A version of #barycentric_weights_v2 that doesn't allow negative weights.
- * Useful when negative values cause problems and points are only ever slightly outside of the triangle.
+ * Useful when negative values cause problems and points are only
+ * ever slightly outside of the triangle.
  */
 void barycentric_weights_v2_clamped(
     const float v1[2], const float v2[2], const float v3[2], const float co[2], float w[3])
@@ -3524,9 +3533,9 @@ void barycentric_weights_v2_quad(const float v1[2],
                                  float w[4])
 {
   /* note: fabsf() here is not needed for convex quads (and not used in interp_weights_poly_v2).
-   *       but in the case of concave/bow-tie quads for the mask rasterizer it gives unreliable results
-   *       without adding absf(). If this becomes an issue for more general usage we could have
-   *       this optional or use a different function - Campbell */
+   * but in the case of concave/bow-tie quads for the mask rasterizer it gives unreliable results
+   * without adding absf(). If this becomes an issue for more general usage we could have
+   * this optional or use a different function - Campbell */
 #define MEAN_VALUE_HALF_TAN_V2(_area, i1, i2) \
   ((_area = cross_v2v2(dirs[i1], dirs[i2])) != 0.0f ? \
        fabsf(((lens[i1] * lens[i2]) - dot_v2v2(dirs[i1], dirs[i2])) / _area) : \
@@ -4338,7 +4347,8 @@ void window_translate_m4(float winmat[4][4], float perspmat[4][4], const float x
 }
 
 /**
- * Frustum planes extraction from a projection matrix (homogeneous 4d vector representations of planes).
+ * Frustum planes extraction from a projection matrix
+ * (homogeneous 4d vector representations of planes).
  *
  * plane parameters can be NULL if you do not need them.
  */
@@ -4814,7 +4824,8 @@ void tangent_from_uv_v3(const float uv1[2],
  * \param pos: current pos array of 'new' positions
  * \param weight: current weight array of 'new'weights (may be NULL pointer if you have no weights)
  * \param rpos: Reference rpos array of 'old' positions
- * \param rweight: Reference rweight array of 'old'weights (may be NULL pointer if you have no weights).
+ * \param rweight: Reference rweight array of 'old'weights
+ * (may be NULL pointer if you have no weights).
  *
  * output
  *
index 3806039..14fde18 100644 (file)
@@ -512,8 +512,9 @@ void BLI_bilinear_interpolation_wrap_char(const unsigned char *buffer,
  * by Ned Greene and Paul S. Heckbert (1986)
  ***************************************************************************/
 
-/* table of (exp(ar) - exp(a)) / (1 - exp(a)) for r in range [0, 1] and a = -2
- * used instead of actual gaussian, otherwise at high texture magnifications circular artifacts are visible */
+/* Table of (exp(ar) - exp(a)) / (1 - exp(a)) for r in range [0, 1] and a = -2
+ * used instead of actual gaussian,
+ * otherwise at high texture magnifications circular artifacts are visible. */
 #define EWA_MAXIDX 255
 const float EWA_WTS[EWA_MAXIDX + 1] = {
     1.f,         0.990965f,   0.982f,      0.973105f,   0.96428f,    0.955524f,   0.946836f,
@@ -621,9 +622,10 @@ void BLI_ewa_filter(const int width,
    * so the ellipse always covers at least some texels. But since the filter is now always larger,
    * it also means that everywhere else it's also more blurry then ideally should be the case.
    * So instead here the ellipse radii are modified instead whenever either is too low.
-   * Use a different radius based on interpolation switch, just enough to anti-alias when interpolation is off,
-   * and slightly larger to make result a bit smoother than bilinear interpolation when interpolation is on
-   * (minimum values: const float rmin = intpol ? 1.f : 0.5f;) */
+   * Use a different radius based on interpolation switch,
+   * just enough to anti-alias when interpolation is off,
+   * and slightly larger to make result a bit smoother than bilinear interpolation when
+   * interpolation is on (minimum values: const float rmin = intpol ? 1.f : 0.5f;) */
   const float rmin = (intpol ? 1.5625f : 0.765625f) / ff2;
   BLI_ewa_imp2radangle(A, B, C, F, &a, &b, &th, &ecc);
   if ((b2 = b * b) < rmin) {
index 71ea1ce..e09fae7 100644 (file)
@@ -1897,8 +1897,10 @@ void blend_m4_m4m4(float out[4][4],
  * A polar-decomposition-based interpolation between matrix A and matrix B.
  *
  * \note This code is about five times slower as the 'naive' interpolation done by #blend_m3_m3m3
- *       (it typically remains below 2 usec on an average i74700, while #blend_m3_m3m3 remains below 0.4 usec).
- *       However, it gives expected results even with non-uniformly scaled matrices, see T46418 for an example.
+ * (it typically remains below 2 usec on an average i74700,
+ * while #blend_m3_m3m3 remains below 0.4 usec).
+ * However, it gives expected results even with non-uniformly scaled matrices,
+ * see T46418 for an example.
  *
  * Based on "Matrix Animation and Polar Decomposition", by Ken Shoemake & Tom Duff
  *
@@ -1937,7 +1939,8 @@ void interp_m3_m3m3(float R[3][3], const float A[3][3], const float B[3][3], con
 }
 
 /**
- * Complete transform matrix interpolation, based on polar-decomposition-based interpolation from #interp_m3_m3m3.
+ * Complete transform matrix interpolation,
+ * based on polar-decomposition-based interpolation from #interp_m3_m3m3.
  *
  * \param R: Resulting interpolated matrix.
  * \param A: Input matrix which is totally effective with `t = 0.0`.
@@ -2626,11 +2629,13 @@ void invert_m4_m4_safe(float Ainv[4][4], const float A[4][4])
  * - #BLI_SPACE_TRANSFORM_SETUP(&data,  ob1, ob2)
  *
  * After that the following calls can be used:
- * - #BLI_space_transform_apply(&data, co);  // converts a coordinate in ob1 space to the corresponding ob2 space.
- * - #BLI_space_transform_invert(&data, co);  // converts a coordinate in ob2 space to the corresponding ob1 space.
+ * - Converts a coordinate in ob1 space to the corresponding ob2 space:
+ *   #BLI_space_transform_apply(&data, co);
+ * - Converts a coordinate in ob2 space to the corresponding ob1 space:
+ *   #BLI_space_transform_invert(&data, co);
  *
- * Same concept as #BLI_space_transform_apply and #BLI_space_transform_invert, but no is normalized after conversion
- * (and not translated at all!):
+ * Same concept as #BLI_space_transform_apply and #BLI_space_transform_invert,
+ * but no is normalized after conversion (and not translated at all!):
  * - #BLI_space_transform_apply_normal(&data, no);
  * - #BLI_space_transform_invert_normal(&data, no);
  */
@@ -2638,12 +2643,14 @@ void invert_m4_m4_safe(float Ainv[4][4], const float A[4][4])
 /**
  * Global-invariant transform.
  *
- * This defines a matrix transforming a point in local space to a point in target space such that its global
- * coordinates remain unchanged.
+ * This defines a matrix transforming a point in local space to a point in target space
+ * such that its global coordinates remain unchanged.
  *
- * In other words, if we have a global point P with local coordinates (x, y, z) and global coordinates (X, Y, Z),
+ * In other words, if we have a global point P with local coordinates (x, y, z)
+ * and global coordinates (X, Y, Z),
  * this defines a transform matrix TM such that (x', y', z') = TM * (x, y, z)
- * where (x', y', z') are the coordinates of P' in target space such that it keeps (X, Y, Z) coordinates in global space.
+ * where (x', y', z') are the coordinates of P' in target space
+ * such that it keeps (X, Y, Z) coordinates in global space.
  */
 void BLI_space_transform_from_matrices(SpaceTransform *data,
                                        const float local[4][4],
@@ -2658,12 +2665,14 @@ void BLI_space_transform_from_matrices(SpaceTransform *data,
 /**
  * Local-invariant transform.
  *
- * This defines a matrix transforming a point in global space such that its local coordinates
- * (from local space to target space) remain unchanged.
+ * This defines a matrix transforming a point in global space
+ * such that its local coordinates (from local space to target space) remain unchanged.
  *
- * In other words, if we have a local point p with local coordinates (x, y, z) and global coordinates (X, Y, Z),
+ * In other words, if we have a local point p with local coordinates (x, y, z)
+ * and global coordinates (X, Y, Z),
  * this defines a transform matrix TM such that (X', Y', Z') = TM * (X, Y, Z)
- * where (X', Y', Z') are the coordinates of p' in global space such that it keeps (x, y, z) coordinates in target space.
+ * where (X', Y', Z') are the coordinates of p' in global space
+ * such that it keeps (x, y, z) coordinates in target space.
  */
 void BLI_space_transform_global_from_matrices(SpaceTransform *data,
                                               const float local[4][4],
index a6331aa..a1c3d16 100644 (file)
@@ -184,7 +184,8 @@ bool BLI_tridiagonal_solve_cyclic(
  *
  * \param func_delta: Callback computing the value of f(x).
  * \param func_jacobian: Callback computing the Jacobian matrix of the function at x.
- * \param func_correction: Callback for forcing the search into an arbitrary custom domain. May be NULL.
+ * \param func_correction: Callback for forcing the search into an arbitrary custom domain.
+ * May be NULL.
  * \param userdata: Data for the callbacks.
  * \param epsilon: Desired precision.
  * \param max_iterations: Limit on the iterations.
index dbfc68a..7c46112 100644 (file)
@@ -93,7 +93,8 @@ static void covariance_m_vn_ex_task_cb(void *__restrict userdata,
  * \param n: the dimension of the vectors (and hence, of the covariance matrix to compute).
  * \param cos_vn: the nD points to compute covariance from.
  * \param nbr_cos_vn: the number of nD coordinates in cos_vn.
- * \param center: the center (or mean point) of cos_vn. If NULL, it is assumed cos_vn is already centered.
+ * \param center: the center (or mean point) of cos_vn. If NULL,
+ * it is assumed cos_vn is already centered.
  * \param use_sample_correction: whether to apply sample correction
  *                              (i.e. get 'sample varince' instead of 'population variance').
  * \return r_covmat the computed covariance matrix.
index 64872e8..3bb60a2 100644 (file)
@@ -57,7 +57,8 @@
 
 #ifdef WIN32
 
-/* return true if the path is absolute ie starts with a drive specifier (eg A:\) or is a UNC path */
+/** Return true if the path is absolute ie starts with a drive specifier
+ * (eg A:\) or is a UNC path. */
 static bool BLI_path_is_abs(const char *name);
 
 #endif /* WIN32 */
@@ -71,8 +72,10 @@ static bool BLI_path_is_abs(const char *name);
  * returning the integer value if found, or 0 if not.
  *
  * \param string: String to scan.
- * \param head: Optional area to return copy of part of string prior to digits, or before dot if no digits.
- * \param tail: Optional area to return copy of part of string following digits, or from dot if no digits.
+ * \param head: Optional area to return copy of part of string prior to digits,
+ * or before dot if no digits.
+ * \param tail: Optional area to return copy of part of string following digits,
+ * or from dot if no digits.
  * \param r_num_len: Optional to return number of digits found.
  */
 int BLI_stringdec(const char *string, char *head, char *tail, ushort *r_num_len)
@@ -282,15 +285,18 @@ void BLI_cleanup_file(const char *relabase, char *path)
  * https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words )
  * by underscores ('_').
  *
- * \note Space case ' ' is a bit of an edge case here - in theory it is allowed, but again can be an issue
- *       in some cases, so we simply replace it by an underscore too (good practice anyway).
- *       REMOVED based on popular demand (see T45900).
- *       Percent '%' char is a bit same case - not recommended to use it, but supported by all decent FS/OS around...
+ * \note Space case ' ' is a bit of an edge case here - in theory it is allowed,
+ * but again can be an issue in some cases, so we simply replace it by an underscore too
+ * (good practice anyway).
+ * REMOVED based on popular demand (see T45900).
+ * Percent '%' char is a bit same case - not recommended to use it,
+ * but supported by all decent FS/OS around.
  *
- * \note On Windows, it also ensures there is no '.' (dot char) at the end of the file, this can lead to issues...
+ * \note On Windows, it also ensures there is no '.' (dot char) at the end of the file,
+ * this can lead to issues.
  *
  * \note On Windows, it also checks for forbidden names
- *       (see https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx ).
+ * (see https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247%28v=vs.85%29.aspx ).
  */
 bool BLI_filename_make_safe(char *fname)
 {
@@ -438,7 +444,8 @@ static int BLI_path_unc_prefix_len(const char *path)
 
 #if defined(WIN32)
 
-/* return true if the path is absolute ie starts with a drive specifier (eg A:\) or is a UNC path */
+/** Return true if the path is absolute ie starts with a drive specifier
+ * (eg A:\) or is a UNC path. */
 static bool BLI_path_is_abs(const char *name)
 {
   return (name[1] == ':' && (name[2] == '\\' || name[2] == '/')) || BLI_path_is_unc(name);
@@ -1302,8 +1309,8 @@ const char *BLI_getenv(const char *env)
 }
 
 /**
- * Strips off nonexistent (or non-accessible) subdirectories from the end of *dir, leaving the path of
- * the lowest-level directory that does exist and we can read.
+ * Strips off nonexistent (or non-accessible) subdirectories from the end of *dir,
+ * leaving the path of the lowest-level directory that does exist and we can read.
  */
 void BLI_make_exist(char *dir)
 {
index 2ca19d1..3e94ae8 100644 (file)
@@ -96,8 +96,9 @@ BLI_INLINE bool is_boundary_edge(uint i_a, uint i_b, const uint coord_last)
  * Assuming we have 2 triangles sharing an edge (2 - 4),
  * check if the edge running from (1 - 3) gives better results.
  *
- * \param lock_degenerate: Use to avoid rotating out of a degenerate state.
- * - When true, an existing zero area face on either side of the (2 - 4) split will return a positive value.
+ * \param lock_degenerate: Use to avoid rotating out of a degenerate state:
+ * - When true, an existing zero area face on either side of the (2 - 4
+ *   split will return a positive value.
  * - When false, the check must be non-biased towards either split direction.
  *
  * \return (negative number means the edge can be rotated, lager == better).
index 0cf3e92..5000b3d 100644 (file)
@@ -553,7 +553,8 @@ void BLI_rctf_transform_pt_v(const rctf *dst,
 /**
  * Calculate a 4x4 matrix representing the transformation between two rectangles.
  *
- * \note Multiplying a vector by this matrix does *not* give the same value as #BLI_rctf_transform_pt_v.
+ * \note Multiplying a vector by this matrix does *not*
+ * give the same value as #BLI_rctf_transform_pt_v.
  */
 void BLI_rctf_transform_calc_m4_pivot_min_ex(
     const rctf *dst, const rctf *src, float matrix[4][4], uint x, uint y)
index 4060ad1..ea15c14 100644 (file)
 /** \file
  * \ingroup bli
  *
- * A light stack-friendly hash library, it uses stack space for relatively small, fixed size hash tables
- * but falls back to heap memory once the stack limits reached (#SMSTACKSIZE).
+ * A light stack-friendly hash library, it uses stack space for relatively small,
+ * fixed size hash tables but falls back to heap memory once the stack limits reached
+ * (#SMSTACKSIZE).
  *
  * based on a doubling hashing approach (non-chaining) which uses more buckets then entries
  * stepping over buckets when two keys share the same hash so any key can find a free bucket.
  *
  * See: https://en.wikipedia.org/wiki/Double_hashing
  *
- * \warning This should _only_ be used for small hashes where allocating a hash every time is unacceptable.
+ * \warning This should _only_ be used for small hashes
+ * where allocating a hash every time is unacceptable.
  * Otherwise #GHash should be used instead.
  *
  * #SmallHashEntry.key
index 01cb635..3b69e25 100644 (file)
@@ -118,7 +118,8 @@ char *BLI_strncpy(char *__restrict dst, const char *__restrict src, const size_t
 }
 
 /**
- * Like BLI_strncpy but ensures dst is always padded by given char, on both sides (unless src is empty).
+ * Like BLI_strncpy but ensures dst is always padded by given char,
+ * on both sides (unless src is empty).
  *
  * \param dst: Destination for copy
  * \param src: Source string to copy
@@ -927,7 +928,8 @@ bool BLI_str_endswith(const char *__restrict str, const char *__restrict end)
  * \param str: The string to search within.
  * \param delim: The set of delimiters to search for, as unicode values.
  * \param sep: Return value, set to the first delimiter found (or NULL if none found).
- * \param suf: Return value, set to next char after the first delimiter found (or NULL if none found).
+ * \param suf: Return value, set to next char after the first delimiter found
+ * (or NULL if none found).
  * \return The length of the prefix (i.e. *sep - str).
  */
 size_t BLI_str_partition(const char *str, const char delim[], const char **sep, const char **suf)
@@ -941,7 +943,8 @@ size_t BLI_str_partition(const char *str, const char delim[], const char **sep,
  * \param str: The string to search within.
  * \param delim: The set of delimiters to search for, as unicode values.
  * \param sep: Return value, set to the first delimiter found (or NULL if none found).
- * \param suf: Return value, set to next char after the first delimiter found (or NULL if none found).
+ * \param suf: Return value, set to next char after the first delimiter found
+ * (or NULL if none found).
  * \return The length of the prefix (i.e. *sep - str).
  */
 size_t BLI_str_rpartition(const char *str, const char delim[], const char **sep, const char **suf)
@@ -956,7 +959,8 @@ size_t BLI_str_rpartition(const char *str, const char delim[], const char **sep,
  * \param end: If non-NULL, the right delimiter of the string.
  * \param delim: The set of delimiters to search for, as unicode values.
  * \param sep: Return value, set to the first delimiter found (or NULL if none found).
- * \param suf: Return value, set to next char after the first delimiter found (or NULL if none found).
+ * \param suf: Return value, set to next char after the first delimiter found
+ * (or NULL if none found).
  * \param from_right: If %true, search from the right of \a str, else, search from its left.
  * \return The length of the prefix (i.e. *sep - str).
  */
@@ -1073,9 +1077,10 @@ size_t BLI_str_format_uint64_grouped(char dst[16], uint64_t num)
  * 1000 -> 1 KB
  * Number of decimal places grows with the used unit (e.g. 1.5 MB, 1.55 GB, 1.545 TB).
  *
- * \param dst: The resulting string. Dimension of 14 to support largest possible value for \a bytes (LLONG_MAX).
- * \param bytes: Number to format
- * \param base_10: Calculate using base 10 (GB, MB, ...) or 2 (GiB, MiB, ...)
+ * \param dst: The resulting string.
+ * Dimension of 14 to support largest possible value for \a bytes (#LLONG_MAX).
+ * \param bytes: Number to format.
+ * \param base_10: Calculate using base 10 (GB, MB, ...) or 2 (GiB, MiB, ...).
  */
 void BLI_str_format_byte_unit(char dst[15], long long int bytes, const bool base_10)
 {
index 9b6ffd8..fa12b4b 100644 (file)
@@ -132,10 +132,13 @@ void BLI_string_split_prefix(const char *string, char *r_pre, char *r_body, cons
 }
 
 /**
- * Finds the best possible flipped (left/right) name. For renaming; check for unique names afterwards.
+ * Finds the best possible flipped (left/right) name.
+ * For renaming; check for unique names afterwards.
  *
- * \param r_name: flipped name, assumed to be a pointer to a string of at least \a name_len size.
- * \param from_name: original name, assumed to be a pointer to a string of at least \a name_len size.
+ * \param r_name: flipped name,
+ * assumed to be a pointer to a string of at least \a name_len size.
+ * \param from_name: original name,
+ * assumed to be a pointer to a string of at least \a name_len size.
  * \param strip_number: If set, remove number extensions.
  */
 void BLI_string_flip_side_name(char *r_name,
@@ -326,7 +329,8 @@ bool BLI_uniquename_cb(UniquenameCheckCallback unique_check,
  *
  * For places where this is used, see constraint.c for example...
  *
- * \param name_offs: should be calculated using offsetof(structname, membername) macro from stddef.h
+ * \param name_offs: should be calculated using offsetof(structname, membername)
+ * macro from stddef.h
  */
 static bool uniquename_find_dupe(ListBase *list, void *vlink, const char *name, int name_offs)
 {
index 57ce4f1..6f9ff02 100644 (file)
@@ -714,13 +714,15 @@ TaskPool *BLI_task_pool_create(TaskScheduler *scheduler, void *userdata)
 
 /**
  * Create a background task pool.
- * In multi-threaded context, there is no differences with \a BLI_task_pool_create(), but in single-threaded case
- * it is ensured to have at least one worker thread to run on (i.e. you do not have to call
- * \a BLI_task_pool_work_and_wait() on it to be sure it will be processed).
+ * In multi-threaded context, there is no differences with #BLI_task_pool_create(),
+ * but in single-threaded case it is ensured to have at least one worker thread to run on
+ * (i.e. you don't have to call #BLI_task_pool_work_and_wait
+ * on it to be sure it will be processed).
  *
- * \note Background pools are non-recursive (that is, you should not create other background pools in tasks assigned
- *       to a background pool, they could end never being executed, since the 'fallback' background thread is already
- *       busy with parent task in single-threaded context).
+ * \note Background pools are non-recursive
+ * (that is, you should not create other background pools in tasks assigned to a background pool,
+ * they could end never being executed, since the 'fallback' background thread is already
+ * busy with parent task in single-threaded context).
  */
 TaskPool *BLI_task_pool_create_background(TaskScheduler *scheduler, void *userdata)
 {
@@ -1078,7 +1080,8 @@ static void parallel_range_single_thread(const int start,
 }
 
 /**
- * This function allows to parallelized for loops in a similar way to OpenMP's 'parallel for' statement.
+ * This function allows to parallelized for loops in a similar way to OpenMP's
+ * 'parallel for' statement.
  *
  * See public API doc of ParallelRangeSettings for description of all settings.
  */
@@ -1264,10 +1267,12 @@ BLI_INLINE int task_parallel_listbasecalc_chunk_size(const int num_threads)
  * \param listbase: The double linked list to loop over.
  * \param userdata: Common userdata passed to all instances of \a func.
  * \param func: Callback function.
- * \param use_threading: If \a true, actually split-execute loop in threads, else just do a sequential forloop
- *                      (allows caller to use any kind of test to switch on parallelization or not).
+ * \param use_threading: If \a true, actually split-execute loop in threads,
+ * else just do a sequential forloop
+ * (allows caller to use any kind of test to switch on parallelization or not).
  *
- * \note There is no static scheduling here, since it would need another full loop over items to count them...
+ * \note There is no static scheduling here,
+ * since it would need another full loop over items to count them.
  */
 void BLI_task_parallel_listbase(struct ListBase *listbase,
                                 void *userdata,
@@ -1336,7 +1341,8 @@ static void parallel_mempool_func(TaskPool *__restrict pool, void *taskdata, int
  * \param mempool: The iterable BLI_mempool to loop over.
  * \param userdata: Common userdata passed to all instances of \a func.
  * \param func: Callback function.
- * \param use_threading: If \a true, actually split-execute loop in threads, else just do a sequential for loop
+ * \param use_threading: If \a true, actually split-execute loop in threads,
+ * else just do a sequential for loop
  * (allows caller to use any kind of test to switch on parallelization or not).
  *
  * \note There is no static scheduling here.