Move the description of records to Record's moduledoc. Closes #1166

Author: alco

lib/elixir/lib/kernel.ex

@@ -1362,155 +1362,16 @@ defmodule Kernel do
   @doc %B"""
   Defines a record.
 
-  A record is a tagged tuple which contains one or more elements
-  and the first element is a module. This macro defines a module
-  that generates accessors to manipulate the record at both
-  compilation and runtime.
+  This macro defines a module that generates accessors to manipulate the record
+  at both compilation and runtime.
+
+  See the `Record` module's documentation for a detailed description of records
+  in Elixir.
 
   ## Examples
 
       defrecord FileInfo, atime: nil, accesses: 0
 
-  The line above will define a module named `FileInfo` which
-  contains a function named `new` that returns a new record
-  and other functions to read and set the values in the
-  record:
-
-      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:
-
-      inspect FileInfo.new, raw: true
-      #=> { FileInfo, nil, nil }
-
-  Besides defining readers and writers for each attribute, Elixir also
-  defines an `update_#{attribute}` function to update the value. Such
-  functions expect a function as argument that receives the current
-  value and must return the new one. For example, every time the file
-  is accessed, the accesses counter can be incremented with:
-
-      file_info.update_accesses(fn(old) -> old + 1 end)
-
-  Which can be also written as:
-
-      file_info.update_accesses(&1 + 1)
-
-  ## Access syntax
-
-  Records in Elixir can be expanded at compilation time to provide
-  pattern matching and faster operations. For example, the clause
-  below will only match if a `FileInfo` is given and the number of
-  accesses is zero:
-
-      def enforce_no_access(FileInfo[accesses: 0]), do: :ok
-
-  The clause above will expand to:
-
-      def enforce_no_access({ FileInfo, _, 0 }), do: :ok
-
-  The downside of using such syntax is that, every time the record
-  changes, your code now needs to be recompiled (which is usually
-  not a concern since Elixir build tools by default recompiles the
-  whole project whenever there is a change).
-
-  Finally, keep in mind that Elixir triggers some optimizations whenever
-  the access syntax is used. For example:
-
-      def no_access?(FileInfo[] = file_info) do
-        file_info.accesses == 0
-      end
-
-  Is translated to:
-
-      def no_access?({ FileInfo, _, _ } = file_info) do
-        elem(file_info, 1) == 0
-      end
-
-  Which provides faster get and set times for record operations.
-
-  ## Runtime introspection
-
-  At runtime, developers can use `__record__` to get information
-  about the given record:
-
-      FileInfo.__record__(:name)
-      #=> FileInfo
-
-      FileInfo.__record__(:fields)
-      #=> [atime: nil, accesses: 0]
-
-  In order to quickly access the index of a field, one can use
-  the `__index__` function:
-
-      FileInfo.__index__(:atime)
-      #=> 0
-
-      FileInfo.__index__(:unknown)
-      #=> nil
-
-  ## Compile-time introspection
-
-  At the compile time, one can access following information about the record
-  from within the record module:
-
-  * `@record_fields` — a keyword list of record fields with defaults
-  * `@record_types` — a keyword list of record fields with types
-
-       defrecord Foo, bar: nil do
-         record_type bar: nil | integer
-         IO.inspect @record_fields
-         IO.inspect @record_types
-       end
-
-  prints out
-
-       [bar: nil]
-       [bar: {:|,[line: ...],[nil,{:integer,[line: ...],nil}]}]
-
-  where the last line is a quoted representation of
-
-       [bar: nil | integer]
-
-  ## Documentation
-
-  By default records are not documented and have `@moduledoc` set to false.
-
-  ## Types
-
-  Every record defines a type named `t` that can be accessed in typespecs.
-  For example, assuming the `Config` record defined above, it could be used
-  in typespecs as follow:
-
-      @spec handle_config(Config.t) :: boolean()
-
-  Inside the record definition, a developer can define his own types too:
-
-      defrecord Config, counter: 0, failures: [] do
-        @type kind :: term
-        record_type counter: integer, failures: [kind]
-      end
-
-  When defining a type, all the fields not mentioned in the type are
-  assumed to have type `term`.
-
-  ## Importing records
-
-  It is also possible to import a public record (a record, defined using
-  `defrecord`) as a set of private macros (as if it was defined using `defrecordp`):
-
-      Record.import Config, as: :config
-
-  See `Record.import/2` and `defrecordp/2` documentation for more information
   """
 
   defmacro defrecord(name, fields, do_block // [])
@@ -1525,15 +1386,15 @@ defmodule Kernel do
   @doc """
   Defines a record with a set of private macros to manipulate it.
 
-  A record is a tagged tuple which contains one or more elements
-  and the first element is a module. This macro defines a set of
-  macros private to the current module to manipulate the record
-  exclusively at compilation time.
+  This macro defines a set of macros private to the current module to
+  manipulate the record exclusively at compilation time.
+
+  `defrecordp` must be used instead of `defrecord` when there is no interest in
+  exposing the record outside of the module it's defined in. In many ways, it
+  is similar to an Erlang record, since it is only available at compilation time.
 
-  `defrecordp` must be used instead of `defrecord` when there is
-  no interest in exposing the record as a whole. In many ways,
-  it is similar to Erlang records, since it is only available at
-  compilation time.
+  See the `Record` module's documentation for a detailed description of records
+  in Elixir.
 
   ## Examples
 
@@ -1578,8 +1439,8 @@ defmodule Kernel do
 
   1) Differently from records, exceptions are documented by default;
 
-  2) Exceptions **must** implement `message/1` as API that return a
-     binary as result;
+  2) Exceptions **must** implement `message/1` -- a function that returns a
+     string;
 
   """
   defmacro defexception(name, fields, opts // [], do_block // []) do

lib/elixir/lib/record.ex

@@ -1,6 +1,155 @@
 defmodule Record do
   @moduledoc """
   Functions to define Elixir records
+
+  A record is a tagged tuple which contains one or more elements and the first
+  element is a module. One creates a record by calling `defrecord` or
+  `defrecordp` which are documented in `Kernel`.
+
+  ## Examples
+
+      defrecord FileInfo, atime: nil, accesses: 0
+
+  The line above will define a module named `FileInfo` which
+  contains a function named `new` that returns a new record
+  and other functions to read and set the values in the
+  record:
+
+      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:
+
+      inspect FileInfo.new, raw: true
+      #=> { FileInfo, nil, nil }
+
+  Besides defining readers and writers for each attribute, Elixir also
+  defines an `update_#{attribute}` function to update the value. Such
+  functions expect a function as argument that receives the current
+  value and must return the new one. For example, every time the file
+  is accessed, the accesses counter can be incremented with:
+
+      file_info.update_accesses(fn(old) -> old + 1 end)
+
+  Which can be also written as:
+
+      file_info.update_accesses(&1 + 1)
+
+  ## Access syntax
+
+  Records in Elixir can be expanded at compilation time to provide
+  pattern matching and faster operations. For example, the clause
+  below will only match if a `FileInfo` is given and the number of
+  accesses is zero:
+
+      def enforce_no_access(FileInfo[accesses: 0]), do: :ok
+
+  The clause above will expand to:
+
+      def enforce_no_access({ FileInfo, _, 0 }), do: :ok
+
+  The downside of using such syntax is that, every time the record
+  changes, your code now needs to be recompiled (which is usually
+  not a concern since Elixir build tools by default recompiles the
+  whole project whenever there is a change).
+
+  Finally, keep in mind that Elixir triggers some optimizations whenever
+  the access syntax is used. For example:
+
+      def no_access?(FileInfo[] = file_info) do
+        file_info.accesses == 0
+      end
+
+  Is translated to:
+
+      def no_access?({ FileInfo, _, _ } = file_info) do
+        elem(file_info, 1) == 0
+      end
+
+  Which provides faster get and set times for record operations.
+
+  ## Runtime introspection
+
+  At runtime, developers can use `__record__` to get information
+  about the given record:
+
+      FileInfo.__record__(:name)
+      #=> FileInfo
+
+      FileInfo.__record__(:fields)
+      #=> [atime: nil, accesses: 0]
+
+  In order to quickly access the index of a field, one can use
+  the `__index__` function:
+
+      FileInfo.__index__(:atime)
+      #=> 0
+
+      FileInfo.__index__(:unknown)
+      #=> nil
+
+  ## Compile-time introspection
+
+  At the compile time, one can access following information about the record
+  from within the record module:
+
+  * `@record_fields` — a keyword list of record fields with defaults
+  * `@record_types` — a keyword list of record fields with types
+
+       defrecord Foo, bar: nil do
+         record_type bar: nil | integer
+         IO.inspect @record_fields
+         IO.inspect @record_types
+       end
+
+  prints out
+
+       [bar: nil]
+       [bar: {:|,[line: ...],[nil,{:integer,[line: ...],nil}]}]
+
+  where the last line is a quoted representation of
+
+       [bar: nil | integer]
+
+  ## Documentation
+
+  By default records are not documented and have `@moduledoc` set to false.
+
+  ## Types
+
+  Every record defines a type named `t` that can be accessed in typespecs.
+  For example, assuming the `Config` record defined above, it could be used
+  in typespecs as follow:
+
+      @spec handle_config(Config.t) :: boolean()
+
+  Inside the record definition, a developer can define his own types too:
+
+      defrecord Config, counter: 0, failures: [] do
+        @type kind :: term
+        record_type counter: integer, failures: [kind]
+      end
+
+  When defining a type, all the fields not mentioned in the type are
+  assumed to have type `term`.
+
+  ## Importing records
+
+  It is also possible to import a public record (a record, defined using
+  `defrecord`) as a set of private macros (as if it was defined using `defrecordp`):
+
+      Record.import Config, as: :config
+
+  See `Record.import/2` and `defrecordp/2` documentation for more information
   """
 
   @doc """