[Bf-blender-cvs] [15bde0d] master: Docs: comments (hash table & beauty fill)

[Campbell Barton]

Commit: 15bde0dbeac81d2fa9f4822753963a3e377ff191
Author: Campbell Barton
Date:   Wed Dec 17 09:51:18 2014 +0100
Branches: master
https://developer.blender.org/rB15bde0dbeac81d2fa9f4822753963a3e377ff191

Docs: comments (hash table & beauty fill)

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

M	source/blender/blenlib/BLI_edgehash.h
M	source/blender/blenlib/BLI_ghash.h
M	source/blender/blenlib/intern/BLI_ghash.c
M	source/blender/blenlib/intern/edgehash.c
M	source/blender/blenlib/intern/polyfill2d_beautify.c
M	source/blender/bmesh/tools/bmesh_beautify.c

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

diff --git a/source/blender/blenlib/BLI_edgehash.h b/source/blender/blenlib/BLI_edgehash.h
index c5323a4..ded4b16 100644
--- a/source/blender/blenlib/BLI_edgehash.h
+++ b/source/blender/blenlib/BLI_edgehash.h
@@ -26,7 +26,6 @@
 /** \file BLI_edgehash.h
  *  \ingroup bli
  *  \author Daniel Dunbar
- *  \brief A general unordered 2-int pair hash table ADT.
  */
 
 #include "BLI_compiler_attrs.h"
diff --git a/source/blender/blenlib/BLI_ghash.h b/source/blender/blenlib/BLI_ghash.h
index 8be19d0..e9f83e7 100644
--- a/source/blender/blenlib/BLI_ghash.h
+++ b/source/blender/blenlib/BLI_ghash.h
@@ -30,7 +30,6 @@
 
 /** \file BLI_ghash.h
  *  \ingroup bli
- *  \brief A general (pointer -> pointer) hash table ADT
  */
 
 #include "BLI_sys_types.h" /* for bool */
diff --git a/source/blender/blenlib/intern/BLI_ghash.c b/source/blender/blenlib/intern/BLI_ghash.c
index 6747e5c..c87b60f 100644
--- a/source/blender/blenlib/intern/BLI_ghash.c
+++ b/source/blender/blenlib/intern/BLI_ghash.c
@@ -28,7 +28,8 @@
 /** \file blender/blenlib/intern/BLI_ghash.c
  *  \ingroup bli
  *
- * A general (pointer -> pointer) hash table ADT
+ * A general (pointer -> pointer) chaining hash table
+ * for 'Abstract Data Types' (known as an ADT Hash Table).
  *
  * \note edgehash.c is based on this, make sure they stay in sync.
  */
diff --git a/source/blender/blenlib/intern/edgehash.c b/source/blender/blenlib/intern/edgehash.c
index 385d9ec..8dd7240 100644
--- a/source/blender/blenlib/intern/edgehash.c
+++ b/source/blender/blenlib/intern/edgehash.c
@@ -23,12 +23,13 @@
 /** \file blender/blenlib/intern/edgehash.c
  *  \ingroup bli
  *
- * A general (pointer -> pointer) hash table ADT
+ * An (edge -> pointer) chaining hash table.
+ * Using unordered int-paits as keys.
  *
- * \note Based on 'BLI_ghash.c', make sure these stay in sync.
+ * \note Based on 'BLI_ghash.c', which is a more generalized hash-table
+ * make sure these stay in sync.
  */
 
-
 #include <stdlib.h>
 #include <string.h>
 #include <limits.h>
diff --git a/source/blender/blenlib/intern/polyfill2d_beautify.c b/source/blender/blenlib/intern/polyfill2d_beautify.c
index c67fe44..c4e333d 100644
--- a/source/blender/blenlib/intern/polyfill2d_beautify.c
+++ b/source/blender/blenlib/intern/polyfill2d_beautify.c
@@ -119,8 +119,9 @@ BLI_INLINE bool is_boundary_edge(unsigned int i_a, unsigned int i_b, const unsig
 }
 /**
  * Assuming we have 2 triangles sharing an edge (2 - 4),
- * check if the edge running from (1 - 3) gives better results
- * (negative number, lager == better).
+ * check if the edge running from (1 - 3) gives better results.
+ *
+ * \return (negative number means the edge can be rotated, lager == better).
  */
 static float quad_v2_rotate_beauty_calc(
         const float v1[2], const float v2[2], const float v3[2], const float v4[2])
diff --git a/source/blender/bmesh/tools/bmesh_beautify.c b/source/blender/bmesh/tools/bmesh_beautify.c
index a5b6026..1c6dc6f 100644
--- a/source/blender/bmesh/tools/bmesh_beautify.c
+++ b/source/blender/bmesh/tools/bmesh_beautify.c
@@ -125,9 +125,6 @@ static void erot_state_alternate(const BMEdge *e, EdRotState *e_state)
 /* -------------------------------------------------------------------- */
 /* Calculate the improvement of rotating the edge */
 
-/**
- * \return a negative value means the edge can be rotated.
- */
 static float bm_edge_calc_rotate_beauty__area(
         const float v1[3], const float v2[3], const float v3[3], const float v4[3])
 {
@@ -272,6 +269,12 @@ static float bm_edge_calc_rotate_beauty__angle(
 	return FLT_MAX;
 }
 
+/**
+ * Assuming we have 2 triangles sharing an edge (2 - 4),
+ * check if the edge running from (1 - 3) gives better results.
+ *
+ * \return (negative number means the edge can be rotated, lager == better).
+ */
 float BM_verts_calc_rotate_beauty(
         const BMVert *v1, const BMVert *v2, const BMVert *v3, const BMVert *v4,
         const short flag, const short method)