commit 1f2f3127500c5018b9760adc7dd025e9f19ae35b
parent 923c66f33eeb41c28c942271c7fd59c6fe6d37a0
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Mon, 9 Dec 2019 10:39:29 +0100
Improve API description
Diffstat:
1 file changed, 16 insertions(+), 15 deletions(-)
diff --git a/src/star-geometry.h b/src/star-geometry.h
@@ -244,26 +244,27 @@ sg3_geometry_create
* callback being provided or not:
* - if provided, the callback must return the consistency status using the
* merge_conflict int* paramater (0 for consistent; any other value for
- * inconsistent, this value being recorded in the report) and the value
- * returned by the callback decides if sg3_geometry_add continue processing
- * other triangles (RES_OK for continue; any other value for stop, this value
- * being returned by sg3_geometry_add);
- * - if not, 2 different not-SG3_UNDEFINED_PROPERTY are inconsistent; the first
- * occuring inconsistency makes sg3_geometry_add stop and return RES_BAD_ARG
- * and the report record the merge_conflict value of 1.
+ * inconsistent, this value being recorded in the report); sg3_geometry_add
+ * never stops/returns an error due to merge_conflict value, but do if
+ * merge_triangle return is not RES_OK (see below);
+ * - if not, a non-SG3_UNDEFINED_PROPERTY is only consistent with itself and
+ * with SG3_UNDEFINED_PROPERTY; the first occuring inconsistency makes
+ * sg3_geometry_add stop and return RES_BAD_ARG and the report records the
+ * merge_conflict value of 1.
* When deduplicating triangles, the first occurence remains (with its
* original index in user world, regardless of deduplication); the only
* way deduplication can change a triangle is to change a property from
* SG3_UNDEFINED_PROPERTY to any defined value.
* The add_triangle and merge_triangle callbacks can be used for external
- * attribute and app-data management. If a call to a callback returns any
- * non-RES_OK value, sg3_geometry_add stops and returns the same error value.
- * In this case the geometry is partially added without any possible undo, but
- * is in a state that allows further calls to sg3_geometry_add.
- * By returning RES_OK even though an inconsistency exists, these callbacks
- * can let sg3_geometry_add process through the end and build a full report;
- * in this scenario, the client code has to proceed according to the
- * inconsistency despite sg3_geometry_add returning RES_OK. */
+ * attribute and app-data management. By returning RES_OK even though an
+ * inconsistency exists, these callbacks can let sg3_geometry_add process
+ * through the end and build a full report; in this scenario, the client code
+ * has to proceed according to the inconsistency despite sg3_geometry_add
+ * returning RES_OK.
+ * If any user callback returns any non-RES_OK value, sg3_geometry_add
+ * stops and returns the same error value. In this case the geometry is
+ * partially added without any possible undo, but is in a state that allows
+ * further calls to sg3_geometry_add. */
SG3_API res_T
sg3_geometry_add
(struct sg3_geometry* geometry,
