Document `FT_Outline_Decompose` degenerate segments.
`FT_Outline_Decompose` does not filter out and can return degenerate
segments in an outline. This can be surprising when attemping to
stroke such an outline. Clarify the existing documentation on this
matter to cover all forms of degeneracy (without specifying exactly
how they will be reported), why they might arise, and better explain in
what cases they may be an issue.
* include/freetype/ftoutlin.h (FT_Outline_Decompose): update
documentation.
Fixes #952.
diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h
index 32ca841..46ebf93 100644
--- a/include/freetype/ftoutln.h
+++ b/include/freetype/ftoutln.h
@@ -109,11 +109,13 @@
* FreeType error code. 0~means success.
*
* @note:
- * A contour that contains a single point only is represented by a 'move
- * to' operation followed by 'line to' to the same point. In most cases,
- * it is best to filter this out before using the outline for stroking
- * purposes (otherwise it would result in a visible dot when round caps
- * are used).
+ * Degenerate contours, segments, and Bezier arcs may be reported. In
+ * most cases, it is best to filter these out before using the outline
+ * for stroking or other path modification purposes (which may cause
+ * degenerate segments to become non-degenrate and visible, like when
+ * stroke caps are used or the path is otherwise outset). Some glyph
+ * outlines may contain deliberate degenerate single points for mark
+ * attachement.
*
* Similarly, the function returns success for an empty outline also
* (doing nothing, this is, not calling any emitter); if necessary, you
