From 48e3825053d01f00f0f4be4f83273d5ba7ac3adc Mon Sep 17 00:00:00 2001
From: Chris Eppstein <chris@eppsteins.net>
Date: Sun, 2 Jan 2011 12:34:16 -0800
Subject: [PATCH] Document Sass Functions

---
 doc-src/Gemfile.lock                          |  2 +-
 doc-src/assets/javascripts/site.js            |  2 +-
 doc-src/content/index/functions.haml          | 18 +++++++++
 doc-src/content/index/mixins.haml             |  2 +-
 .../content/stylesheets/partials/_code.scss   | 10 ++---
 .../content/stylesheets/partials/_theme.scss  |  2 +-
 .../layouts/partials/reference/functions.haml | 19 +++++++++
 .../layouts/partials/reference/mixins.haml    |  2 +-
 doc-src/layouts/reference.haml                |  2 +
 doc-src/lib/stylesheets.rb                    | 33 +++++++++++++++-
 doc-src/lib/stylesheets/sass_extensions.rb    | 39 +++++++++++++------
 .../sass_extensions/functions/colors.rb       |  5 +--
 12 files changed, 109 insertions(+), 27 deletions(-)
 create mode 100644 doc-src/content/index/functions.haml
 create mode 100644 doc-src/layouts/partials/reference/functions.haml

diff --git a/doc-src/Gemfile.lock b/doc-src/Gemfile.lock
index d9511225..ac01405d 100644
--- a/doc-src/Gemfile.lock
+++ b/doc-src/Gemfile.lock
@@ -8,7 +8,7 @@ GIT
 PATH
   remote: ..
   specs:
-    compass (0.11.alpha.4.e11f103)
+    compass (0.11.alpha.4.d67a43a)
       chunky_png (~> 0.10.3)
       sass (>= 3.1.0.alpha.50)
 
diff --git a/doc-src/assets/javascripts/site.js b/doc-src/assets/javascripts/site.js
index b273aee4..e977a384 100644
--- a/doc-src/assets/javascripts/site.js
+++ b/doc-src/assets/javascripts/site.js
@@ -109,7 +109,7 @@ $('document').ready(function(){
       changeTheme();
       event.preventDefault();
 
-    // View source for mixins
+    // View source for mixins & functions
     } else if (target.attr("rel") == "view source") {
       $(target.attr("href")).toggle();
       event.preventDefault();
diff --git a/doc-src/content/index/functions.haml b/doc-src/content/index/functions.haml
new file mode 100644
index 00000000..6f918437
--- /dev/null
+++ b/doc-src/content/index/functions.haml
@@ -0,0 +1,18 @@
+---
+title: Compass Documentation | All Functions
+crumb: Docs
+body_id: home
+---
+%article
+  %h1#logo Sass Based Functions
+  
+  - all_functions.sort_by{|i| i.first.identifier}.each do |item, functions|
+    %h3= link_to item[:title], item
+    %ul
+      - functions.sort_by{|f| f.name}.each do |f|
+        %li= f.sass_signature(:html)
+
+  %h1#logo All Ruby Based Functions
+  %ul
+    - Sass::Script::Functions.public_instance_methods.sort_by{|m| m.to_s}.each do |m|
+      %li= m.to_s.gsub("_","-")
diff --git a/doc-src/content/index/mixins.haml b/doc-src/content/index/mixins.haml
index 3980026e..4dc8a10b 100644
--- a/doc-src/content/index/mixins.haml
+++ b/doc-src/content/index/mixins.haml
@@ -10,5 +10,5 @@ body_id: home
     %h3= link_to item[:title], item
     %ul
       - mixins.sort_by{|m| m.name}.each do |m|
-        %li= mixin_signature(m)
+        %li= m.sass_signature(:none, :html)
 
diff --git a/doc-src/content/stylesheets/partials/_code.scss b/doc-src/content/stylesheets/partials/_code.scss
index 9349495f..710b75f3 100644
--- a/doc-src/content/stylesheets/partials/_code.scss
+++ b/doc-src/content/stylesheets/partials/_code.scss
@@ -1,18 +1,18 @@
 //html.sass .mixin-source .scss, html.scss .mixin-source .sass { @extend .hide;}
-.mixin-source, .example-source {
+.mixin-source, .example-source, .function-source {
   position: relative; @extend .fixed-font;
   .syntaxhighlighter, pre {
   &.scss, &.sass, &.css, &.haml, &.html { display: none; } } }
 
-html.sass { .mixin-source .syntaxhighlighter.sass, .example-source .syntaxhighlighter.sass { display: block; } }
-html.scss { .mixin-source .syntaxhighlighter.scss, .example-source .syntaxhighlighter.scss { display: block; } }
+html.sass { .mixin-source, .example-source, .function-source { .syntaxhighlighter.sass { display: block; } } }
+html.scss { .mixin-source, .example-source, .function-source { .syntaxhighlighter.scss { display: block; } } }
 html.css .example-source .syntaxhighlighter.css { display: block; }
 html.html .example-source .syntaxhighlighter.html { display: block; }
 html.haml .example-source .syntaxhighlighter.haml { display: block; }
 
 
 
-.mixin-source { display: none; }
+.mixin-source, .function-source { display: none; }
 
 html.light .syntaxhighlighter, html.dark .syntaxhighlighter {
   margin: 0 0 2px;
@@ -59,7 +59,7 @@ h3 { @include round-corners;
   a { text-decoration: none;}
   code, .arg { font-weight: normal; }
 }
-h3.mixin { @include round-top-corners; margin-bottom: 2px;}
+h3.mixin, h3.function { @include round-top-corners; margin-bottom: 2px;}
 .arg {
   display: inline-block;
   padding: 0 2px;
diff --git a/doc-src/content/stylesheets/partials/_theme.scss b/doc-src/content/stylesheets/partials/_theme.scss
index d5c4d114..e60b6270 100644
--- a/doc-src/content/stylesheets/partials/_theme.scss
+++ b/doc-src/content/stylesheets/partials/_theme.scss
@@ -74,7 +74,7 @@
   &.sass a[rel=sass], &.scss a[rel=scss], &.css a[rel=css], &.html a[rel=html], &.haml a[rel=haml] { color: $heading; color: rgba($heading, .7); @extend .round-corners-em; @extend .inset-panel-#{$theme}; }
 
   #version { color: rgba($heading, .3); a { color: rgba($nav-link, .7); } }
-  .mixin-source, .example-source { @extend .mixin-panel-#{$theme};
+  .mixin-source, .example-source, .function-source { @extend .mixin-panel-#{$theme};
     .container textarea { color: $code; }
   }
   h2 a.help { color: $heading;}
diff --git a/doc-src/layouts/partials/reference/functions.haml b/doc-src/layouts/partials/reference/functions.haml
new file mode 100644
index 00000000..51b945e3
--- /dev/null
+++ b/doc-src/layouts/partials/reference/functions.haml
@@ -0,0 +1,19 @@
+- if (functions = functions(@item)).any?
+  %h2 Functions
+
+  - functions.each do |function|
+    %a{:href=>"#function-#{function.name}-source", :rel => "view source"} view source
+    %h3.function{:id=>"function-#{function.name}"}
+      %a.permalink{:href => "#function-#{function.name}"}= function.sass_signature(:html)
+    .function-source{:id=>"function-#{function.name}-source"}
+      %pre.source-code.sass= function.to_sass
+      %pre.source-code.scss= function.to_scss
+
+    .source-documentation
+      = format_doc(function.comment)
+      - if (examples = examples(@item, function)).any?
+        %dl.examples
+          - examples.each do |example|
+            %dt= link_to example.item[:title], example
+            - if example.item[:description]
+              %dd= example.item[:description]
diff --git a/doc-src/layouts/partials/reference/mixins.haml b/doc-src/layouts/partials/reference/mixins.haml
index 8a4a60cb..e3b35441 100644
--- a/doc-src/layouts/partials/reference/mixins.haml
+++ b/doc-src/layouts/partials/reference/mixins.haml
@@ -4,7 +4,7 @@
   - mixin_defs.each do |mixin|
     %a{:href=>"#mixin-#{mixin.name}-source", :rel => "view source"} view source
     %h3.mixin{:id=>"mixin-#{mixin.name}"}
-      %a.permalink{:href => "#mixin-#{mixin.name}"}= mixin_signature(mixin)
+      %a.permalink{:href => "#mixin-#{mixin.name}"}= mixin.sass_signature(:none, :html)
     .mixin-source{:id=>"mixin-#{mixin.name}-source"}
       %pre.source-code.sass= mixin.to_sass
       %pre.source-code.scss= mixin.to_scss
diff --git a/doc-src/layouts/reference.haml b/doc-src/layouts/reference.haml
index ef5cafe4..cad6909c 100644
--- a/doc-src/layouts/reference.haml
+++ b/doc-src/layouts/reference.haml
@@ -20,4 +20,6 @@
 
 = render "partials/reference/constants"
 
+= render "partials/reference/functions"
+
 = render "partials/reference/mixins"
diff --git a/doc-src/lib/stylesheets.rb b/doc-src/lib/stylesheets.rb
index 113baa20..bd15624b 100644
--- a/doc-src/lib/stylesheets.rb
+++ b/doc-src/lib/stylesheets.rb
@@ -118,6 +118,26 @@ def mixins(item)
   mixins.reject{|m| m.comment =~ /@private/}
 end
 
+def functions(item)
+  sass_tree = tree(item)
+  functions = []
+  comment = nil
+  sass_tree.children.each do |child|
+    if child.is_a?(Sass::Tree::FunctionNode)
+      child.comment = comment && Sass::Tree::CommentNode.clean(comment)
+      comment = nil
+      functions << child
+    elsif child.is_a?(Sass::Tree::CommentNode)
+      comment ||= ""
+      comment << "\n" unless comment.empty?
+      comment << child.docstring
+    else
+      comment = nil
+    end
+  end
+  functions.reject{|m| m.comment =~ /@private/}
+end
+
 def constants(item)
   sass_tree = tree(item)
   constants = []
@@ -165,8 +185,17 @@ def all_mixins
   all_mixins
 end
 
-def mixin_signature(mixin, format = :html)
-  mixin.sass_signature(:none, format)
+def all_functions
+  all_functions = []
+  @items.each do |item|
+    next unless item.identifier =~ %r{/reference}
+    next unless item[:stylesheet]
+    fns = functions(item)
+    if fns.any?
+      all_functions << [item, fns]
+    end
+  end
+  all_functions
 end
 
 def example_items
diff --git a/doc-src/lib/stylesheets/sass_extensions.rb b/doc-src/lib/stylesheets/sass_extensions.rb
index dcf77717..a22ca076 100644
--- a/doc-src/lib/stylesheets/sass_extensions.rb
+++ b/doc-src/lib/stylesheets/sass_extensions.rb
@@ -19,18 +19,9 @@ module Sass
     class VariableNode < Node
       attr_accessor :comment unless method_defined? :comment
     end
-    class MixinDefNode < Node
-      attr_accessor :name unless method_defined? :name
-      attr_accessor :args unless method_defined? :args
-      attr_accessor :comment unless method_defined? :comment
-      def sass_signature(mode = :definition, format = :text)
-        prefix = case mode
-        when :definition
-          "="
-        when :include
-          "+"
-        end
-        "#{prefix}#{name}#{arglist_to_sass(format)}"
+    module HasSignature
+      def sass_signature(format = :text)
+        "#{name}#{arglist_to_sass(format)}"
       end
 
       private
@@ -57,6 +48,30 @@ module Sass
         sass_str
       end
     end
+    class MixinDefNode < Node
+      attr_accessor :name unless method_defined? :name
+      attr_accessor :args unless method_defined? :args
+      attr_accessor :comment unless method_defined? :comment
+      unless included_modules.include?(HasSignature)
+        include HasSignature
+        alias sass_signature_without_prefix sass_signature
+        def sass_signature(mode = :definition, format = :text)
+          prefix = case mode
+          when :definition
+            "="
+          when :include
+            "+"
+          end
+          "#{prefix}#{sass_signature_without_prefix(format)}"
+        end
+      end
+    end
+    class FunctionNode < Node
+      attr_accessor :name unless method_defined? :name
+      attr_accessor :args unless method_defined? :args
+      attr_accessor :comment unless method_defined? :comment
+      include HasSignature unless included_modules.include?(HasSignature)
+    end
     class ImportNode < RootNode
       attr_accessor :imported_filename unless method_defined? :imported_filename
     end
diff --git a/lib/compass/sass_extensions/functions/colors.rb b/lib/compass/sass_extensions/functions/colors.rb
index f7ba0173..70be6162 100644
--- a/lib/compass/sass_extensions/functions/colors.rb
+++ b/lib/compass/sass_extensions/functions/colors.rb
@@ -1,11 +1,10 @@
 module Compass::SassExtensions::Functions::Colors
-  include Compass::Util
 
   # a genericized version of lighten/darken so that negative values can be used.
   def adjust_lightness(color, amount)
     assert_type color, :Color
     assert_type amount, :Number
-    color.with(:lightness => restrict(color.lightness + amount.value, 0..100))
+    color.with(:lightness => Compass::Util.restrict(color.lightness + amount.value, 0..100))
   end
 
   # Scales a color's lightness by some percentage.
@@ -21,7 +20,7 @@ module Compass::SassExtensions::Functions::Colors
   def adjust_saturation(color, amount)
     assert_type color, :Color
     assert_type amount, :Number
-    color.with(:saturation => restrict(color.saturation + amount.value, 0..100))
+    color.with(:saturation => Compass::Util.restrict(color.saturation + amount.value, 0..100))
   end
 
   # Scales a color's saturation by some percentage.