Document postwalk behaviour and html nodes

lib/floki.ex

@@ -61,11 +61,13 @@ defmodule Floki do
   inside a list.
   """
 
+  @type html_declaration :: {:pi, String.t(), [html_attribute()]}
   @type html_comment :: {:comment, String.t()}
   @type html_doctype :: {:doctype, String.t(), String.t(), String.t()}
   @type html_attribute :: {String.t(), String.t()}
   @type html_tag :: {String.t(), [html_attribute()], [html_tag() | String.t() | html_comment()]}
-  @type html_tree :: [html_comment() | html_doctype() | html_tag()]
+  @type html_node :: html_comment() | html_doctype() | html_tag() | html_declaration()
+  @type html_tree :: [html_node()]
 
   @doc """
   Parses a HTML Document from a String.
@@ -326,7 +328,8 @@ defmodule Floki do
   Traverses and updates a HTML tree structure.
 
   This function returns a new tree structure that is the result of applying the
-  given `fun` on all nodes.
+  given `fun` on all nodes. The tree is traversed in a post-walk fashion, where
+  the children are traversed before the parent.
 
   The function `fun` receives a tuple with `{name, attributes, children}`, and
   should either return a similar tuple or `nil` to delete the current node.
@@ -347,15 +350,17 @@ defmodule Floki do
       {"div", [], []}
   """
 
-  @spec traverse_and_update(html_tree(), (html_tag() -> html_tag() | nil)) :: html_tree()
+  @spec traverse_and_update(html_tree(), (html_node() -> html_node() | nil)) :: html_tree()
 
   defdelegate traverse_and_update(html_tree, fun), to: Floki.Traversal
 
   @doc """
   Traverses and updates a HTML tree structure with an accumulator.
 
   This function returns a new tree structure and the final value of accumulator
-  which are the result of applying the given `fun` on all nodes.
+  which are the result of applying the given `fun` on all nodes. The tree is
+  traversed in a post-walk fashion, where the children are traversed before
+  the parent.
 
   The function `fun` receives a tuple with `{name, attributes, children}` and
   an accumulator, and should return a 2-tuple like `{new_node, new_acc}`, where
@@ -386,8 +391,8 @@ defmodule Floki do
   @spec traverse_and_update(
           html_tree(),
           traverse_acc,
-          (html_tag(), traverse_acc -> {html_tag() | nil, traverse_acc})
-        ) :: {html_tree(), traverse_acc}
+          (html_node(), traverse_acc -> {html_node() | nil, traverse_acc})
+        ) :: {html_node(), traverse_acc}
         when traverse_acc: any()
 
   defdelegate traverse_and_update(html_tree, acc, fun), to: Floki.Traversal

lib/floki/html_tree.ex

@@ -35,9 +35,6 @@ defmodule Floki.HTMLTree do
 
   def build(html_tuples) when is_list(html_tuples) do
     reducer = fn
-      {:pi, _}, tree ->
-        tree
-
       {:pi, _, _}, tree ->
         tree
 

lib/floki/raw_html.ex

@@ -47,8 +47,8 @@ defmodule Floki.RawHTML do
   defp build_raw_html([{:comment, comment} | tail], html, encoder),
     do: build_raw_html(tail, [html, "<!--", comment | "-->"], encoder)
 
-  defp build_raw_html([{:pi, "xml", attrs} | tail], html, encoder) do
-    build_raw_html(tail, [html, "<?xml ", tag_attrs(attrs) | "?>"], encoder)
+  defp build_raw_html([{:pi, tag, attrs} | tail], html, encoder) do
+    build_raw_html(tail, [html, "<?", tag, " ", tag_attrs(attrs) | "?>"], encoder)
   end
 
   defp build_raw_html([{:doctype, type, public, system} | tail], html, encoder) do