[freetype2] master e34a860a0: Document `FT_Outline_Decompose` degenerate segments.

[Werner Lemberg]

branch: master
commit e34a860a07ce60ae23ee4c01cb3c8076dc24c2b7
Author: Ben Wagner <bungeman@chromium.org>
Commit: Werner Lemberg <wl@gnu.org>

    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.
---
 include/freetype/ftoutln.h | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h
index 32ca84119..46ebf9371 100644
--- a/include/freetype/ftoutln.h
+++ b/include/freetype/ftoutln.h
@@ -109,11 +109,13 @@ FT_BEGIN_HEADER
    *   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