Merge pull request #1193 from ericmj/docs-overridable

Document `super` and add more docs to `defoverridable`

Author: José Valim

lib/elixir/lib/kernel.ex

@@ -1379,13 +1379,13 @@ defmodule Kernel do
       file_info = FileInfo.new(atime: now())
       file_info.atime         #=> Returns the value of atime
       file_info.atime(now())  #=> Updates the value of atime
-      
+
       # Update multiple attributes at once:
       file_info.update(atime: now(), accesses: 1)
-      
+
       # Obtain the keywords representation of a record:
       file_info.to_keywords   #=> [accesses: 1, atime: {1370,7171,911705}]
-      
+
 
   A record is simply a tuple where the first element is the record
   module name. We can get the record raw representation as follow:
@@ -1835,9 +1835,34 @@ defmodule Kernel do
   end
 
   @doc """
-  Makes the given functions in the current module overridable.
-  An overridable function is lazily defined, allowing a
-  developer to customize it.
+  Makes the given functions in the current module overridable. An overridable
+  function is lazily defined, allowing a developer to customize it.
+
+  ## Example
+
+      defmodule DefaultMod do
+        defmacro __using__(_opts) do
+          quote do
+            def test(x, y) do
+              x + y
+            end
+
+            defoverridable [test: 2]
+          end
+        end
+      end
+
+      defmodule InheritMod do
+        use DefaultMod
+
+        def test(x, y) do
+          x * y + super
+        end
+      end
+
+  As seen as in the example `super` can be used to call the default
+  implementation, if no arguments are given to `super` it will be implictly
+  given the arguments of the current function.
   """
   defmacro defoverridable(tuples) do
     quote do

lib/elixir/lib/kernel/special_forms.ex

@@ -24,7 +24,7 @@ defmodule Kernel.SpecialForms do
 
   ## Examples
 
-      :{}.(1,2,3)
+      iex> { 1, 2, 3 }
       { 1, 2, 3 }
 
   """
@@ -35,7 +35,7 @@ defmodule Kernel.SpecialForms do
 
   ## Examples
 
-      :[].(1,2,3)
+      iex> [ 1, 2, 3 ]
       [ 1, 2, 3 ]
 
   """
@@ -810,4 +810,12 @@ defmodule Kernel.SpecialForms do
 
   """
   defmacro __aliases__(args)
+
+  @doc """
+  Calls the overriden function when overriding it with `defoverridable`. If no
+  arguments are given to `super` the overriden function will be called with the
+  same arguments as the current one. See `Kernel.defoverridable` for more
+  information and documentation.
+  """
+  defmacro super(args)
 end

lib/elixir/lib/module.ex

@@ -362,7 +362,8 @@ defmodule Module do
   @doc """
   Makes the given functions in the given module overridable.
   An overridable function is lazily defined, allowing a
-  developer to customize it.
+  developer to customize it. See `Kernel.defoverridable` for
+  more information and documentation.
   """
   def make_overridable(module, tuples) do
     assert_not_compiled!(:make_overridable, module)