Index: flag.h
===================================================================
--- flag.h	(revision 27598)
+++ flag.h	(revision 27599)
@@ -57,39 +57,39 @@
 /*** object flags ***/
 typedef enum {
 	PCB_FLAG_NO           = 0x00000,
-	PCB_FLAG_PIN          = 0x00001,
-	PCB_FLAG_VIA          = 0x00002,
-	PCB_FLAG_FOUND        = 0x00004,
-	PCB_FLAG_HOLE         = 0x00008,
-	PCB_FLAG_NOPASTE      = 0x00008,
-	PCB_FLAG_RAT          = 0x00010,
-	PCB_FLAG_PININPOLY    = 0x00010,
-	PCB_FLAG_CLEARPOLY    = 0x00010,
-	PCB_FLAG_HIDENAME     = 0x00010,
-	PCB_FLAG_DISPLAYNAME  = 0x00020,
-	PCB_FLAG_CLEARLINE    = 0x00020,
-	PCB_FLAG_FULLPOLY     = 0x00020,
-	PCB_FLAG_SELECTED     = 0x00040,
-	PCB_FLAG_ONSOLDER     = 0x00080,
-	PCB_FLAG_AUTO         = 0x00080,
-	PCB_FLAG_SQUARE       = 0x00100,
-	PCB_FLAG_RUBBEREND    = 0x00200,
-	PCB_FLAG_WARN         = 0x00200,
-	PCB_FLAG_USETHERMAL   = 0x00400,
+	PCB_FLAG_PIN          = 0x00001, /* unused */
+	PCB_FLAG_VIA          = 0x00002, /* when a rat line has this flag, it's displayed as a circle ("via needs to connect to sorrunding poly") */
+	PCB_FLAG_FOUND        = 0x00004, /* the "green highlight" find.c does for the user */
+	PCB_FLAG_HOLE         = 0x00008, /* legacy io_pcb only (broken?) */
+	PCB_FLAG_NOPASTE      = 0x00008, /* legacy io_pcb only (broken?) */
+	PCB_FLAG_RAT          = 0x00010, /* rat line objects are marked with this flag */
+	PCB_FLAG_PININPOLY    = 0x00010, /* unused */
+	PCB_FLAG_CLEARPOLY    = 0x00010, /* polygon objects that are willing to be cleared */
+	PCB_FLAG_HIDENAME     = 0x00010, /* legacy io_pcb only */
+	PCB_FLAG_DISPLAYNAME  = 0x00020, /* unused */
+	PCB_FLAG_CLEARLINE    = 0x00020, /* non-polygon objects clear polygons */
+	PCB_FLAG_FULLPOLY     = 0x00020, /* DANGEROUS: keep all islands of a poly */
+	PCB_FLAG_SELECTED     = 0x00040, /* user selection ("cyan") */
+	PCB_FLAG_ONSOLDER     = 0x00080, /* mirror text because it is on the solder side */
+	PCB_FLAG_AUTO         = 0x00080, /* object placed by autorouter */
+	PCB_FLAG_SQUARE       = 0x00100, /* line cap: square instead of the default round */
+	PCB_FLAG_RUBBEREND    = 0x00200, /* unused */
+	PCB_FLAG_WARN         = 0x00200, /* "orange" warning e.g. for shorts */
+	PCB_FLAG_USETHERMAL   = 0x00400, /* legacy io_pcb only */
 	PCB_FLAG_ONSILK       = 0x00400, /* Obsolete, old files used this to indicate lines drawn on silk. (Used by io_pcb for compatibility.) */
-	PCB_FLAG_OCTAGON      = 0x00800,
-	PCB_FLAG_DRC          = 0x01000,
-	PCB_FLAG_LOCK         = 0x02000,
-	PCB_FLAG_EDGE2        = 0x04000,
+	PCB_FLAG_OCTAGON      = 0x00800, /* legacy io_pcb only */
+	PCB_FLAG_DRC          = 0x01000, /* temporary, invisible */
+	PCB_FLAG_LOCK         = 0x02000, /* user lock (no move, no edit) */
+	PCB_FLAG_EDGE2        = 0x04000, /* unused */
 	PCB_FLAG_VISIT        = 0x08000, /* marker to avoid re-visiting an object */
-	PCB_FLAG_NONETLIST    = 0x10000,
+	PCB_FLAG_NONETLIST    = 0x10000, /* object is not part of the netlist, don't warn for netlist issues */
 	PCB_FLAG_MINCUT       = 0x20000, /* used by the mincut short find code */
 	PCB_FLAG_ONPOINT      = 0x40000, /* crosshair is on line point or arc point */
-	PCB_FLAG_TERMNAME     = 0x80000, 
+	PCB_FLAG_TERMNAME     = 0x80000, /* object is a terminal */
 	PCB_FLAG_DRC_INTCONN  = 0x100000,/* Set for objects are put on the DRC mark because of an intconn */
-	PCB_FLAG_CLEARPOLYPOLY= 0x200000,
-	PCB_FLAG_DYNTEXT      = 0x400000,
-	PCB_FLAG_FLOATER      = 0x800000
+	PCB_FLAG_CLEARPOLYPOLY= 0x200000,/* polygon clearning other polygons */
+	PCB_FLAG_DYNTEXT      = 0x400000,/* templated text */
+	PCB_FLAG_FLOATER      = 0x800000 /* object ignores subc lock */
 /*	PCB_FLAG_NOCOPY     = (PCB_FLAG_FOUND | CONNECTEDFLAG | PCB_FLAG_ONPOINT)*/
 } pcb_flag_values_t;