diff --git a/src/autofit/afadjust.c b/src/autofit/afadjust.c
index c60a97d40..8baeb0c46 100644
--- a/src/autofit/afadjust.c
+++ b/src/autofit/afadjust.c
@@ -13,10 +13,12 @@
     #include <hb-ot.h>
 #endif
 
-/*TODO: find out whether capital u/U with accent entries are needed*/
-/*the accent won't merge with the rest of the glyph because the accent mark is sitting above empty space*/
 /*
   All entries in this list must be sorted by unicode codepoint ascending
+  The table entries are 3 numbers consisting of:
+  - unicode codepoint.  THESE MUST BE LISTED IN ASCENDING ORDER
+  - the vertical adjustment type.  One of the entries in AF_VerticalSeparationAdjustmentType
+  - 0 if the topmost contour is a tilde and should be prevented from flattening.
 */
 FT_LOCAL_ARRAY_DEF( AF_AdjustmentDatabaseEntry )
 adjustment_database[] =
diff --git a/src/autofit/aflatin.c b/src/autofit/aflatin.c
index 703106577..c189c4f2f 100644
--- a/src/autofit/aflatin.c
+++ b/src/autofit/aflatin.c
@@ -2880,6 +2880,14 @@ af_latin_remove_tilde_points_from_edges( AF_GlyphHints hints,
     }
   } while ( p != first_point );
 }
+/*
+The tilde unflatenning algorithm sometimes goes too far and makes an
+unusually high tilde, where decreasing the ppem will increase the height
+instead of a steady decrease in height as less pixels are used.
+
+The n tilde on times new roman with forced autofitting on,
+16.5-18 ppem font size exhibits this behaviour.
+*/
 void
 af_latin_stretch_tildes( AF_GlyphHints hints,
                          FT_Int glyph_index )