diff --git a/src/graphics/graphics_vertexformat.js b/src/graphics/graphics_vertexformat.js
index 778badc86ea..4958583efa3 100644
--- a/src/graphics/graphics_vertexformat.js
+++ b/src/graphics/graphics_vertexformat.js
@@ -12,25 +12,58 @@ pc.extend(pc, function () {
/**
* @name pc.VertexFormat
- * @class A vertex format is a descriptor that defines the layout of vertex element data inside
- * a pc.VertexBuffer object.
- * @description Returns a new pc.VertexFormat object. It is constructed from a description
- * that explicitly defines how data is to be laid out inside a vertex buffer (pc.VertexBuffer).
- * The description is defined as an array of elements, where each element is an object with the
- * following properties:
- * semantic: pc.SEMANTIC_.
- * components: the number of components used by the element.
- * type: (pc.ELEMENTTYPE_).
- * normalize: true to remap element values to a range of 0 to 1. Defaults to false.
+ * @class A vertex format is a descriptor that defines the layout of vertex data inside
+ * a {@link pc.VertexBuffer}.
+ * @description Returns a new pc.VertexFormat object.
* @param {pc.GraphicsDevice} graphicsDevice The graphics device used to manage this vertex format.
- * @param {Object[]} description An array of vertex element descriptions.
+ * @param {Object[]} description An array of vertex attribute descriptions.
+ * @param {Number} description[].semantic The meaning of the vertex element. This is used to link
+ * the vertex data to a shader input. Can be:
+ *
+ * - pc.SEMANTIC_POSITION
+ * - pc.SEMANTIC_NORMAL
+ * - pc.SEMANTIC_TANGENT
+ * - pc.SEMANTIC_BLENDWEIGHT
+ * - pc.SEMANTIC_BLENDINDICES
+ * - pc.SEMANTIC_COLOR
+ * - pc.SEMANTIC_TEXCOORD0
+ * - pc.SEMANTIC_TEXCOORD1
+ * - pc.SEMANTIC_TEXCOORD2
+ * - pc.SEMANTIC_TEXCOORD3
+ * - pc.SEMANTIC_TEXCOORD4
+ * - pc.SEMANTIC_TEXCOORD5
+ * - pc.SEMANTIC_TEXCOORD6
+ * - pc.SEMANTIC_TEXCOORD7
+ *
+ * If vertex data has a meaning other that one of those listed above, use the user-defined
+ * semantics: pc.SEMANTIC_ATTR0 to pc.SEMANTIC_ATTR15.
+ * @param {Number} description[].components The number of components of the vertex attribute.
+ * Can be 1, 2, 3 or 4.
+ * @param {Number} description[].type The data type of the attribute. Can be:
+ *
+ * - pc.ELEMENTTYPE_INT8
+ * - pc.ELEMENTTYPE_UINT8
+ * - pc.ELEMENTTYPE_INT16
+ * - pc.ELEMENTTYPE_UINT16
+ * - pc.ELEMENTTYPE_INT32
+ * - pc.ELEMENTTYPE_UINT32
+ * - pc.ELEMENTTYPE_FLOAT32
+ *
+ * @param {Boolean} description[].normalize If true, vertex attribute data will be mapped from a
+ * 0 to 255 range down to 0 to 1 when fed to a shader. If false, vertex attribute data is left
+ * unchanged. If this property is unspecified, false is assumed.
* @example
+ * // Specify 3-component positions (x, y, z)
+ * var vertexFormat = new pc.VertexFormat(graphicsDevice, [
+ * { semantic: pc.SEMANTIC_POSITION, components: 3, type: pc.ELEMENTTYPE_FLOAT32 },
+ * ]);
+ * @example
+ * // Specify 2-component positions (x, y), a texture coordinate (u, v) and a vertex color (r, g, b, a)
* var vertexFormat = new pc.VertexFormat(graphicsDevice, [
* { semantic: pc.SEMANTIC_POSITION, components: 2, type: pc.ELEMENTTYPE_FLOAT32 },
* { semantic: pc.SEMANTIC_TEXCOORD0, components: 2, type: pc.ELEMENTTYPE_FLOAT32 },
* { semantic: pc.SEMANTIC_COLOR, components: 4, type: pc.ELEMENTTYPE_UINT8, normalize: true }
* ]);
- *
* @author Will Eastcott
*/
var VertexFormat = function (graphicsDevice, description) {