-/** A single vertex component. Symbolic names are provided for commonly used
-attributes. These are aliased with with generic attributes, so be careful when
-picking your attribute indices. */
+/** A single vertex attribute. Commonly used attributes are named by their
+semantical meaning in the standard shaders. Texture coordinates and generic
+attributes can additionally be given an index. There are four texture
+coordinate attributes available. The number of available generic attributes
+depends on implementation limits, but is at least five.
+
+RAW_ATTRIB is handled in a special way; creating an indexed attribute based on
+it uses the index as raw attribute number. Only use it if you know what you
+are doing. */