split html box processing code

reduce the module size of the html box handling code by
 splitting into smaller sections.

No functional code change.

1 files changed, 48 insertions, 0 deletions

diff --git a/content/handlers/html/box_construct.h b/content/handlers/html/box_construct.h
index e93f515e4..f4bd119b1 100644
--- a/content/handlers/html/box_construct.h
+++ b/content/handlers/html/box_construct.h
@@ -19,6 +19,54 @@
 /**
  * \file
  * HTML Box tree construction interface.
+ *
+ * This stage of rendering converts a tree of dom_nodes (produced by libdom)
+ * to a tree of struct box. The box tree represents the structure of the
+ * document as given by the CSS display and float properties.
+ *
+ * For example, consider the following HTML:
+ * \code
+ *   <h1>Example Heading</h1>
+ *   <p>Example paragraph <em>with emphasised text</em> etc.</p>       \endcode
+ *
+ * This would produce approximately the following box tree with default CSS
+ * rules:
+ * \code
+ *   BOX_BLOCK (corresponds to h1)
+ *     BOX_INLINE_CONTAINER
+ *       BOX_INLINE "Example Heading"
+ *   BOX_BLOCK (p)
+ *     BOX_INLINE_CONTAINER
+ *       BOX_INLINE "Example paragraph "
+ *       BOX_INLINE "with emphasised text" (em)
+ *       BOX_INLINE "etc."                                             \endcode
+ *
+ * Note that the em has been collapsed into the INLINE_CONTAINER.
+ *
+ * If these CSS rules were applied:
+ * \code
+ *   h1 { display: table-cell }
+ *   p { display: table-cell }
+ *   em { float: left; width: 5em }                                    \endcode
+ *
+ * then the box tree would instead look like this:
+ * \code
+ *   BOX_TABLE
+ *     BOX_TABLE_ROW_GROUP
+ *       BOX_TABLE_ROW
+ *         BOX_TABLE_CELL (h1)
+ *           BOX_INLINE_CONTAINER
+ *             BOX_INLINE "Example Heading"
+ *         BOX_TABLE_CELL (p)
+ *           BOX_INLINE_CONTAINER
+ *             BOX_INLINE "Example paragraph "
+ *             BOX_FLOAT_LEFT (em)
+ *               BOX_BLOCK
+ *                 BOX_INLINE_CONTAINER
+ *                   BOX_INLINE "with emphasised text"
+ *             BOX_INLINE "etc."                                       \endcode
+ *
+ * Here implied boxes have been added and a float is present.
  */
 
 #ifndef NETSURF_HTML_BOX_CONSTRUCT_H