update the docs for compass/utilities/general/clearfix

doc-src/content/reference/compass/utilities/general/clearfix.haml

@@ -12,4 +12,5 @@ classnames:
 ---
 - render 'reference' do
   %p
-    Lorem ipsum dolor sit amet.
+    A clearfix will extend the bottom of the element to enclose any
+    floated elements it contains.

frameworks/compass/stylesheets/compass/utilities/general/_clearfix.scss

@@ -1,24 +1,34 @@
+// @doc off
+// Extends the bottom of the element to enclose any floats it contains.
+// @doc on
+
 @import "hacks";
 
-//**
+// This basic method is preferred for the usual case, when positioned
-// Extends the element to enclose any floats it contains.
+// content will not show outside the bounds of the container.
-// This basic method is preferred for the usual case, when positioned content will not show outside the bounds of the container.
+//
-// Recommendations include using this in conjunction with a width:
+// Recommendations include using this in conjunction with a width.
-// http://www.quirksmode.org/blog/archives/2005/03/clearing_floats.html
+// Credit: [quirksmode.org](http://www.quirksmode.org/blog/archives/2005/03/clearing_floats.html)
 @mixin clearfix {
   overflow: hidden;
-  @include has-layout; }
+  @include has-layout;
+}
 
-//**
+// This older method from Position Is Everything called
-// Extends the element to enclose any floats it contains.
+// [Easy Clearing](http://www.positioniseverything.net/easyclearing.html)
-// This older "Easy Clearing" method has the advantage of allowing positioned elements to hang outside the bounds of the container, at the expense of more tricky CSS.
+// has the advantage of allowing positioned elements to hang
-// http://www.positioniseverything.net/easyclearing.html
+// outside the bounds of the container at the expense of more tricky CSS.
+//
+// This method of clearing might cause a gap at the bottom of the page in
+// some browsers when used on the last element of the page.
 @mixin pie-clearfix {
   &:after {
-    content: " ";
+    content    : " ";
-    display: block;
+    display    : block;
-    height: 0;
+    height     : 0;
-    clear: both;
+    clear      : both;
-    overflow: hidden;
+    overflow   : hidden;
-    visibility: hidden; }
+    visibility : hidden;
-  @include has-layout; }
+  }
+  @include has-layout;
+}