From 25f1dedb74aa98c28ea392c6a92613d44227fd76 Mon Sep 17 00:00:00 2001
From: Chris Andrew <chris@hexus.io>
Date: Wed, 6 Jun 2018 15:12:12 +0100
Subject: [PATCH] Started documenting Bitmap Font data structures.

---
 src/gameobjects/bitmaptext/ParseRetroFont.js  |  2 +
 .../bitmaptext/ParseXMLBitmapFont.js          | 38 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/src/gameobjects/bitmaptext/ParseRetroFont.js b/src/gameobjects/bitmaptext/ParseRetroFont.js
index b916e1ddd..84e612bc9 100644
--- a/src/gameobjects/bitmaptext/ParseRetroFont.js
+++ b/src/gameobjects/bitmaptext/ParseRetroFont.js
@@ -15,6 +15,8 @@ var GetValue = require('../../utils/object/GetValue');
  *
  * @param {Phaser.Scene} scene - A reference to the Phaser Scene.
  * @param {Phaser.GameObjects.RetroFont.Config} config - The font configuration object.
+ *
+ * @return {object} [description]
  */
 var ParseRetroFont = function (scene, config)
 {
diff --git a/src/gameobjects/bitmaptext/ParseXMLBitmapFont.js b/src/gameobjects/bitmaptext/ParseXMLBitmapFont.js
index f6d8bd154..e67618597 100644
--- a/src/gameobjects/bitmaptext/ParseXMLBitmapFont.js
+++ b/src/gameobjects/bitmaptext/ParseXMLBitmapFont.js
@@ -14,7 +14,43 @@ function getValue (node, attribute)
     return parseInt(node.getAttribute(attribute), 10);
 }
 
+// TODO: These typedefs should be kept somewhere else.
+// TODO: Elaborate on the kerning property description.
+
 /**
+ * The font data for an individual character of a Bitmap Font.
+ *
+ * Describes the character's position, size, offset and kerning.
+ *
+ * @typedef {object} BitmapFontCharacterData
+ *
+ * @property {number} x - The x position of the character.
+ * @property {number} y - The y position of the character.
+ * @property {number} width - The width of the character.
+ * @property {number} height - The height of the character.
+ * @property {number} centerX - The center x position of the character.
+ * @property {number} centerY - The center y position of the character.
+ * @property {number} xOffset - The x offset of the character.
+ * @property {number} yOffset - The y offset of the character.
+ * @property {object} data - Extra data for the character.
+ * @property {object} kerning - Kerning values. [description]
+ */
+
+/**
+ * Bitmap Font data that can be used by a BitmapText Game Object.
+ *
+ * @typedef {object} BitmapFontData
+ *
+ * @property {string} font - The name of the font.
+ * @property {number} size - The size of the font.
+ * @property {number} lineHeight - The line height of the font.
+ * @property {boolean} retroFont - Whether this font is a retro font (monospace).
+ * @property {Object.<number, BitmapFontCharacterData>} chars - The character data of the font, keyed by character code. Each character datum includes a position, size, offset and more.
+ */
+
+/**
+ * Parse an XML font so you can pass it to the BitmapText constructor and create a BitmapText object.
+ *
  * @function ParseXMLBitmapFont
  * @since 3.0.0
  * @private
@@ -23,6 +59,8 @@ function getValue (node, attribute)
  * @param {integer} [xSpacing=0] - The x-axis spacing to add between each letter.
  * @param {integer} [ySpacing=0] - The y-axis spacing to add to the line height.
  * @param {Phaser.Textures.Frame} [frame] - The texture frame to take into account while parsing.
+ *
+ * @return {BitmapFontData} The parsed Bitmap Font data.
  */
 var ParseXMLBitmapFont = function (xml, xSpacing, ySpacing, frame)
 {