Merge pull request #2415 from alco/list-format

Reformat unordered lists in all docstrings

Author: José Valim

lib/eex/lib/eex.ex

@@ -14,32 +14,31 @@ defmodule EEx do
 
   This module provides 3 main APIs for you to use:
 
-  1) Evaluate a string (`eval_string`) or a file (`eval_file`)
-     directly. This is the simplest API to use but also the
-     slowest, since the code is evaluated and not compiled before;
+    1. Evaluate a string (`eval_string`) or a file (`eval_file`)
+       directly. This is the simplest API to use but also the
+       slowest, since the code is evaluated and not compiled before.
 
-  2) Define a function from a string (`function_from_string`)
-     or a file (`function_from_file`). This allows you to embed
-     the template as a function inside a module which will then
-     be compiled. This is the preferred API if you have access
-     to the template at compilation time;
+    2. Define a function from a string (`function_from_string`)
+       or a file (`function_from_file`). This allows you to embed
+       the template as a function inside a module which will then
+       be compiled. This is the preferred API if you have access
+       to the template at compilation time.
 
-  3) Compile a string (`compile_string`) or a file (`compile_file`)
-     into Elixir syntax tree. This is the API used by both functions
-     above and is available to you if you want to provide your own
-     ways of handling the compiled template.
+    3. Compile a string (`compile_string`) or a file (`compile_file`)
+       into Elixir syntax tree. This is the API used by both functions
+       above and is available to you if you want to provide your own
+       ways of handling the compiled template.
 
   ## Options
 
   All functions in this module accepts EEx-related options.
   They are:
 
-  * `:line` - the line to be used as the template start.
-              Defaults to 1;
-  * `:file` - the file to be used in the template.
-              Defaults to the given file the template is read from
-              or to "nofile" when compiling from a string;
-  * `:engine` - the EEx engine to be used for compilation.
+    * `:line`   - the line to be used as the template start. Defaults to 1.
+    * `:file`   - the file to be used in the template. Defaults to the given
+                  file the template is read from or to "nofile" when compiling
+                  from a string.
+    * `:engine` - the EEx engine to be used for compilation.
 
   ## Engine
 

lib/eex/lib/eex/engine.ex

@@ -3,25 +3,22 @@ defmodule EEx.Engine do
   This is the basic EEx engine that ships with Elixir.
   An engine needs to implement three functions:
 
-  * `handle_body(quoted)` - receives the final built quoted
-    expression, should do final post-processing and return a
-    quoted expression;
+    * `handle_body(quoted)` - receives the final built quoted
+      expression, should do final post-processing and return a
+      quoted expression.
 
-  * `handle_text(buffer, text)` - it receives the buffer,
-    the text and must return a new quoted expression;
+    * `handle_text(buffer, text)` - it receives the buffer,
+      the text and must return a new quoted expression.
 
-  * `handle_expr(buffer, marker, expr)` - it receives the buffer,
-    the marker, the expr and must return a new quoted expression;
+    * `handle_expr(buffer, marker, expr)` - it receives the buffer,
+      the marker, the expr and must return a new quoted expression.
 
-    The marker is what follows exactly after `<%`. For example,
-    `<% foo %>` has an empty marker, but `<%= foo %>` has `"="`
-    as marker. The allowed markers so far are:
+      The marker is what follows exactly after `<%`. For example,
+      `<% foo %>` has an empty marker, but `<%= foo %>` has `"="`
+      as marker. The allowed markers so far are: `""` and `"="`.
 
-    * `""`
-    * `"="`
-
-    Read `handle_expr/3` below for more information about the markers
-    implemented by default by this engine.
+      Read `handle_expr/3` below for more information about the markers
+      implemented by default by this engine.
   """
 
   use Behaviour

lib/eex/lib/eex/tokenizer.ex

@@ -5,11 +5,11 @@ defmodule EEx.Tokenizer do
   Tokenizes the given char list or binary.
   It returns 4 different types of tokens as result:
 
-  * {:text, contents}
-  * {:expr, line, marker, contents}
-  * {:start_expr, line, marker, contents}
-  * {:middle_expr, line, marker, contents}
-  * {:end_expr, line, marker, contents}
+    * `{:text, contents}`
+    * `{:expr, line, marker, contents}`
+    * `{:start_expr, line, marker, contents}`
+    * `{:middle_expr, line, marker, contents}`
+    * `{:end_expr, line, marker, contents}`
 
   """
   def tokenize(bin, line) when is_binary(bin) do

lib/elixir/lib/application.ex

@@ -83,8 +83,8 @@ defmodule Application do
   setup where applications takeover and failovers are configured. This particular
   aspect of applications can be read with more detail in the OTP documentation:
 
-  * http://www.erlang.org/doc/man/application.html
-  * http://www.erlang.org/doc/design_principles/applications.html
+    * http://www.erlang.org/doc/man/application.html
+    * http://www.erlang.org/doc/design_principles/applications.html
 
   A developer may also implement the `stop/1` callback (automatically defined
   by `use Application`) which does any application cleanup. It receives the
@@ -152,9 +152,8 @@ defmodule Application do
 
   ## Options
 
-  * `:timeout` - the timeout for the change (defaults to 5000ms);
-
-  * `:persistent` - persists the given value on application load and reloads;
+    * `:timeout`    - the timeout for the change (defaults to 5000ms)
+    * `:persistent` - persists the given value on application load and reloads
 
   If `put_env/4` is called before the application is loaded, the application
   environment values specified in the `.app` file will override the ones
@@ -223,13 +222,16 @@ defmodule Application do
 
   The `type` argument specifies the type of the application:
 
-  * `:permanent` - if `app` terminates, all other applications and the entire
-    node are also terminated;
-  * `:transient` - if `app` terminates with `:normal` reason, it is reported
-    but no other applications are terminated. If a transient application terminates
-    abnormally, all other applications and the entire node are also terminated;
-  * `:temporary` - if `app` termiantes, it is reported but no other applications
-    are terminated (the default);
+    * `:permanent` - if `app` terminates, all other applications and the entire
+      node are also terminated.
+
+    * `:transient` - if `app` terminates with `:normal` reason, it is reported
+      but no other applications are terminated. If a transient application
+      terminates abnormally, all other applications and the entire node are
+      also terminated.
+
+    * `:temporary` - if `app` termiantes, it is reported but no other
+      applications are terminated (the default).
 
   Note that it is always possible to stop an application explicitly by calling
   `stop/1`. Regardless of the type of the application, no other applications will

lib/elixir/lib/bitwise.ex

@@ -24,8 +24,8 @@ defmodule Bitwise do
   Allow a developer to use this module in their programs with
   the following options:
 
-  * `:only_operators` - Include only operators;
-  * `:skip_operators` - Skip operators;
+    * `:only_operators` - include only operators
+    * `:skip_operators` - skip operators
 
   """
   defmacro __using__(options) do

lib/elixir/lib/code.ex

@@ -59,21 +59,24 @@ defmodule Code do
 
   Those options can be:
 
-  * `:file` - the file to be considered in the evaluation
-  * `:line` - the line on which the script starts
-  * `:delegate_locals_to` - delegate local calls to the given module,
-    the default is to not delegate
+    * `:file`               - the file to be considered in the evaluation
+    * `:line`               - the line on which the script starts
+    * `:delegate_locals_to` - delegate local calls to the given module,
+                              the default is to not delegate
 
   Additionally, the following scope values can be configured:
 
-  * `:aliases` - a list of tuples with the alias and its target
-  * `:requires` - a list of modules required
-  * `:functions` - a list of tuples where the first element is a module
-    and the second a list of imported function names and arity. The list
-    of function names and arity must be sorted
-  * `:macros` - a list of tuples where the first element is a module
-    and the second a list of imported macro names and arity. The list
-    of function names and arity must be sorted
+    * `:aliases` - a list of tuples with the alias and its target
+
+    * `:requires` - a list of modules required
+
+    * `:functions` - a list of tuples where the first element is a module
+      and the second a list of imported function names and arity; the list
+      of function names and arity must be sorted
+
+    * `:macros` - a list of tuples where the first element is a module
+      and the second a list of imported macro names and arity; the list
+      of function names and arity must be sorted
 
   Notice that setting any of the values above overrides Elixir's default
   values. For example, setting `:requires` to `[]`, will no longer
@@ -198,13 +201,13 @@ defmodule Code do
 
   ## Options
 
-  * `:file` - The filename to be used in stacktraces
-    and the file reported in the `__ENV__` variable.
+    * `:file` - the filename to be used in stacktraces
+      and the file reported in the `__ENV__` variable
 
-  * `:line` - The line reported in the `__ENV__` variable.
+    * `:line` - the line reported in the `__ENV__` variable
 
-  * `:existing_atoms_only` - When `true`, raises an error
-    when non-existing atoms are found by the tokenizer.
+    * `:existing_atoms_only` - when `true`, raises an error
+      when non-existing atoms are found by the tokenizer
 
   ## Macro.to_string/2
 
@@ -324,17 +327,18 @@ defmodule Code do
 
   Available options are:
 
-  * `:docs` - when `true`, retain documentation in the compiled module,
-    `true` by default;
+    * `:docs` - when `true`, retain documentation in the compiled module,
+      `true` by default
 
-  * `:debug_info` - when `true`, retain debug information in the compiled module.
-    This allows a developer to reconstruct the original source
-    code, `false` by default;
+    * `:debug_info` - when `true`, retain debug information in the compiled
+      module; this allows a developer to reconstruct the original source
+      code, `false` by default
 
-  * `:ignore_module_conflict` - when `true`, override modules that were already defined
-    without raising errors, `false` by default;
+    * `:ignore_module_conflict` - when `true`, override modules that were
+      already defined without raising errors, `false` by default
 
-  * `:warnings_as_errors` - cause compilation to fail when warnings are generated;
+    * `:warnings_as_errors` - cause compilation to fail when warnings are
+      generated
 
   """
   def compiler_options(opts) do
@@ -472,14 +476,14 @@ defmodule Code do
 
   The return value depends on the `kind` value:
 
-  * `:docs` - list of all docstrings attached to functions and macros
-    using the `@doc` attribute
+    * `:docs` - list of all docstrings attached to functions and macros
+      using the `@doc` attribute
 
-  * `:moduledoc` - tuple `{<line>, <doc>}` where `line` is the line on
-    which module definition starts and `doc` is the string
-    attached to the module using the `@moduledoc` attribute
+    * `:moduledoc` - tuple `{<line>, <doc>}` where `line` is the line on
+      which module definition starts and `doc` is the string
+      attached to the module using the `@moduledoc` attribute
 
-  * `:all` - a keyword list with both `:docs` and `:moduledoc`
+    * `:all` - a keyword list with both `:docs` and `:moduledoc`
 
   """
   def get_docs(module, kind) when is_atom(module) do

lib/elixir/lib/dict.ex

@@ -49,36 +49,36 @@ defmodule Dict do
 
   The client module must contain the following functions:
 
-  * `delete/2`
-  * `fetch/2`
-  * `put/3`
-  * `reduce/3`
-  * `size/1`
+    * `delete/2`
+    * `fetch/2`
+    * `put/3`
+    * `reduce/3`
+    * `size/1`
 
   All functions, except `reduce/3`, are required by the Dict behaviour.
   `reduce/3` must be implemtented as per the Enumerable protocol.
 
   Based on these functions, `Dict` generates default implementations
   for the following functions:
 
-  * `drop/2`
-  * `equal?/2`
-  * `fetch!/2`
-  * `get/2`
-  * `get/3`
-  * `has_key?/2`
-  * `keys/1`
-  * `merge/2`
-  * `merge/3`
-  * `pop/2`
-  * `pop/3`
-  * `put_new/3`
-  * `split/2`
-  * `take/2`
-  * `to_list/1`
-  * `update/4`
-  * `update!/3`
-  * `values/1`
+    * `drop/2`
+    * `equal?/2`
+    * `fetch!/2`
+    * `get/2`
+    * `get/3`
+    * `has_key?/2`
+    * `keys/1`
+    * `merge/2`
+    * `merge/3`
+    * `pop/2`
+    * `pop/3`
+    * `put_new/3`
+    * `split/2`
+    * `take/2`
+    * `to_list/1`
+    * `update/4`
+    * `update!/3`
+    * `values/1`
 
   All of these functions are defined as overridable, so you can provide
   your own implementation if needed.

lib/elixir/lib/enum.ex

@@ -39,9 +39,9 @@ defprotocol Enumerable do
 
   It must be a tagged tuple with one of the following "tags":
 
-  * `:cont`    - the enumeration should continue
-  * `:halt`    - the enumeration should halt immediately
-  * `:suspend` - the enumeration should be suspended immediately
+    * `:cont`    - the enumeration should continue
+    * `:halt`    - the enumeration should halt immediately
+    * `:suspend` - the enumeration should be suspended immediately
 
   Depending on the accumulator value, the result returned by
   `Enumerable.reduce/3` will change. Please check the `result`