Merge pull request #1502 from jwarwick/code_formatting

Fixed docs typos and added code markers around functions in docs

Author: José Valim

lib/elixir/lib/path.ex

@@ -9,7 +9,7 @@ defmodule Path do
 
   The majority of the functions in this module do not
   interact with the file system, except for a few functions
-  that require it (like `Path.wildcard` and `Path.expand`).
+  that require it (like `wildcard/1` and `expand/1`).
   """
 
   alias :filename, as: FN
@@ -19,7 +19,7 @@ defmodule Path do
 
   @doc """
   Converts the given path to an absolute one. Unlike
-  `Path.expand/1`, no attempt is made to resolve `..`, `.` or `~`.
+  `expand/1`, no attempt is made to resolve `..`, `.` or `~`.
 
   ## Unix examples
 
@@ -43,9 +43,9 @@ defmodule Path do
 
   @doc """
   Builds a path from `relative_to` to `path`. If `path` is already
-  an absolute path, `relative_to` is ignored. See also `Path.relative/2`.
+  an absolute path, `relative_to` is ignored. See also `relative/2`.
 
-  Unlike `Path.expand/2`, no attempt is made to
+  Unlike `expand/2`, no attempt is made to
   resolve `..`, `.` or `~`.
 
   ## Examples
@@ -80,7 +80,7 @@ defmodule Path do
   expanding any `.` and `..` characters. If the path is already an
   absolute path, `relative_to` is ignored.
 
-  Note, that this function treats `path` with leading `~` as
+  Note, that this function treats `path` with a leading `~` as
   an absolute one.
 
   The second argument is first expanded to an absolute path.
@@ -461,7 +461,7 @@ defmodule Path do
 
   Imagine you have a directory called `projects` with three Elixir projects
   inside of it: `elixir`, `ex_doc` and `dynamo`. You can find all `.beam` files
-  inside the ebin directory of each project as follows:
+  inside the `ebin` directory of each project as follows:
 
       Path.wildcard("projects/*/ebin/**/*.beam")
 

lib/elixir/lib/string.ex

@@ -6,22 +6,22 @@ defmodule String do
 
   The functions in this module act according to the
   Unicode Standard, version 6.2.0. For example,
-  `titlecase`, `downcase`, `strip` are provided by this
+  `capitalize/1`, `downcase/1`, `strip/1` are provided by this
   module.
 
   Besides this module, Elixir provides more low-level
-  operations that works directly with binaries. Some
+  operations that work directly with binaries. Some
   of those can be found in the `Kernel` module, as:
 
-  * `binary_part/2` and `binary_part/3` - retrieves part of the binary
-  * `bit_size/1` and `byte_size/1` - size related functions
-  * `is_bitstring/1` and `is_binary/1` - type checking function
-  * Plus a bunch of conversion functions, like `binary_to_atom/2`,
-    `binary_to_integer/2`, `binary_to_term/1` and their opposite
-    like `integer_to_binary/2`
+  * `Kernel.binary_part/2` and `Kernelbinary_part/3` - retrieves part of the binary
+  * `Kernel.bit_size/1` and `Kernel.byte_size/1` - size related functions
+  * `Kernel.is_bitstring/1` and `Kernel.is_binary/1` - type checking function
+  * Plus a number of conversion functions, like `Kernel.binary_to_atom/2`,
+    `Kernel.binary_to_integer/2`, `Kernel.binary_to_term/1` and their opposite
+    like `Kernel.integer_to_binary/2`
 
-  Finally, [the `:binary` module](http://erlang.org/doc/man/binary.html)
-  provides a couple other functions that works on the byte level.
+  Finally, the [`:binary` module](http://erlang.org/doc/man/binary.html)
+  provides a few other functions that work on the byte level.
 
   ## Codepoints and graphemes
 
@@ -93,7 +93,7 @@ defmodule String do
   codepoint needs to be rejected.
 
   This module relies on this behaviour to ignore such invalid
-  characters. For example, `String.length` is going to return
+  characters. For example, `length/1` is going to return
   a correct result even if an invalid codepoint is fed into it.
 
   In other words, this module expects invalid data to be detected
@@ -108,7 +108,7 @@ defmodule String do
 
   @doc """
   Checks if a string is printable considering it is encoded
-  as UTF-8. Returns true if so, false otherwise.
+  as UTF-8. Returns `true` if so, `false` otherwise.
 
   ## Examples
 
@@ -200,7 +200,7 @@ defmodule String do
   end
 
   @doc """
-  Splits a string on sub strings at each Unicode whitespace
+  Splits a string on substrings at each Unicode whitespace
   occurrence with leading and trailing whitespace ignored.
 
   ## Examples
@@ -217,12 +217,12 @@ defmodule String do
   defdelegate split(binary), to: String.Unicode
 
   @doc """
-  Divides a string into sub strings based on a pattern,
-  returning a list of these sub string. The pattern can
+  Divides a string into substrings based on a pattern,
+  returning a list of these substrings. The pattern can
   be a string, a list of strings or a regular expression.
 
   The string is split into as many parts as possible by
-  default, unless the `global` option is set to false.
+  default, unless the `global` option is set to `false`.
 
   ## Examples
 
@@ -258,7 +258,7 @@ defmodule String do
   end
 
   @doc """
-  Convert all characters on the given string to upcase.
+  Convert all characters on the given string to uppercase.
 
   ## Examples
 
@@ -274,7 +274,7 @@ defmodule String do
   defdelegate upcase(binary), to: String.Unicode
 
   @doc """
-  Convert all characters on the given string to downcase.
+  Convert all characters on the given string to lowercase.
 
   ## Examples
 
@@ -291,11 +291,11 @@ defmodule String do
 
   @doc """
   Converts the first character in the given string to
-  titlecase and the remaining to downcase.
+  uppercase and the remaining to lowercase.
 
   This relies on the titlecase information provided
   by the Unicode Standard. Note this function makes
-  no attempt in capitalizing all words in the string
+  no attempt to capitalize all words in the string
   (usually known as titlecase).
 
   ## Examples
@@ -430,7 +430,7 @@ defmodule String do
   @doc """
   Returns a new binary based on `subject` by replacing the parts
   matching `pattern` for `replacement`. By default, it replaces
-  all entries, except if the `global` option is set to false.
+  all entries, except if the `global` option is set to `false`.
 
   If the replaced part must be used in `replacement`, then the
   position or the positions where it is to be inserted must be
@@ -533,7 +533,7 @@ defmodule String do
   remaining of the string or `:no_codepoint` in case
   the string reached its end.
 
-  As the other functions in the String module, this
+  As with other functions in the String module, this
   function does not check for the validity of the codepoint.
   That said, if an invalid codepoint is found, it will
   be returned by this function.
@@ -674,7 +674,7 @@ defmodule String do
 
   @doc """
   Returns the last grapheme from an utf8 string,
-  nil if the string is empty.
+  `nil` if the string is empty.
 
   ## Examples
 
@@ -762,7 +762,7 @@ defmodule String do
   @doc """
   Returns a substring starting at the offset given by the first, and
   a length given by the second.
-  If the offset is greater than string length, than it returns nil.
+  If the offset is greater than string length, than it returns `nil`.
 
   ## Examples
 
@@ -827,8 +827,8 @@ defmodule String do
 
   @doc """
   Converts a string to an integer. If successful, returns a
-  tuple of form {integer, remainder of string}. If unsuccessful,
-  returns :error.
+  tuple of the form `{integer, remainder of string}`. If unsuccessful,
+  returns `:error`.
 
   ## Examples
 
@@ -852,9 +852,9 @@ defmodule String do
 
   @doc """
   Converts a string to a float. If successful, returns a
-  tuple of form {float, remainder of string}. If unsuccessful,
-  returns :error. If given an integer value, will return
-  same as to_integer/1.
+  tuple of the form `{float, remainder of string}`. If unsuccessful,
+  returns `:error`. If given an integer value, will return
+  the same value as `to_integer/1`.
 
   ## Examples
 
@@ -885,8 +885,8 @@ defmodule String do
   end
 
   @doc """
-  Returns true if `string` starts with any of the prefixes given, otherwise
-  false. `prefixes` can be either a single prefix or a list of prefixes.
+  Returns `true` if `string` starts with any of the prefixes given, otherwise
+  `false`. `prefixes` can be either a single prefix or a list of prefixes.
 
   ## Examples
 
@@ -921,8 +921,8 @@ defmodule String do
   end
 
   @doc """
-  Returns true if `string` ends with any of the suffixes given, otherwise
-  false. `suffixes` can be either a single suffix or a list of suffixes.
+  Returns `true` if `string` ends with any of the suffixes given, otherwise
+  `false`. `suffixes` can be either a single suffix or a list of suffixes.
 
   ## Examples
 
@@ -960,7 +960,7 @@ defmodule String do
   end
 
   @doc """
-  Returns true if `string` contains match, otherwise false.
+  Returns `true` if `string` contains match, otherwise `false`.
   `matches` can be either a single string or a list of strings.
 
   ## Examples

lib/elixir/lib/system.ex

@@ -79,7 +79,7 @@ defmodule System do
   end
 
   @doc """
-  Returns the current working directory or nil if one
+  Returns the current working directory or `nil` if one
   is not available.
   """
   def cwd do
@@ -98,7 +98,7 @@ defmodule System do
 
   @doc """
   Returns the user home (platform independent).
-  It returns nil if no user home is set.
+  It returns `nil` if no user home is set.
   """
   def user_home do
     case :os.type() do
@@ -108,8 +108,8 @@ defmodule System do
   end
 
   @doc """
-  Same as `user_home` but raises `System.NoHomeError`
-  instead of returning nil if no user home is set.
+  Same as `user_home/0` but raises `System.NoHomeError`
+  instead of returning `nil` if no user home is set.
   """
   def user_home! do
     user_home || raise NoHomeError
@@ -139,7 +139,7 @@ defmodule System do
   4. `C:\TMP` on Windows or `/tmp` on Unix
   5.  As a last resort, the current working directory
 
-  Returns nil if none of the above are writable.
+  Returns `nil` if none of the above are writable.
   """
   def tmp_dir do
     write_env_tmp_dir('TMPDIR') ||
@@ -151,7 +151,7 @@ defmodule System do
 
   @doc """
   Same as `tmp_dir` but raises `System.NoTmpDirError`
-  instead of returning nil if no temp dir is set.
+  instead of returning `nil` if no temp dir is set.
   """
   def tmp_dir! do
     tmp_dir || raise NoTmpDirError
@@ -249,7 +249,7 @@ defmodule System do
 
   @doc """
   Returns the value of the environment variable
-  `varname` as a binary, or nil if the environment
+  `varname` as a binary, or `nil` if the environment
   variable is undefined.
   """
   @spec get_env(binary) :: binary | nil
@@ -317,7 +317,7 @@ defmodule System do
 
   For integer status, Erlang runtime system closes all ports and allows async
   threads to finish their operations before exiting. To exit without such
-  flushing, pass options [flush: false] instead.
+  flushing, pass options `[flush: false]` instead.
 
   For more information, check: http://www.erlang.org/doc/man/erlang.html#halt-2
 

lib/elixir/lib/uri.ex

@@ -31,16 +31,16 @@ defmodule URI do
 
   @doc """
   Returns the default port for a given scheme.
-  If the scheme is unknown to URI, returns nil.
-  Any scheme may be registered via `URI.default_port/2`.
+  If the scheme is unknown to URI, returns `nil`.
+  Any scheme may be registered via `default_port/2`.
   """
   def default_port(scheme) when is_binary(scheme) do
     { :ok, dict } = :application.get_env(:elixir, :uri)
     Dict.get(dict, scheme)
   end
 
   @doc """
-  Registers a scheme with a default port into Elixir.
+  Registers a scheme with a default port.
   """
   def default_port(scheme, port) when is_binary(scheme) and port > 0 do
     { :ok, dict } = :application.get_env(:elixir, :uri)
@@ -49,10 +49,10 @@ defmodule URI do
 
   @doc """
   Takes an enumerable (containing a sequence of two-item tuples)
-  and returns a string of k=v&k2=v2... where keys and values are
-  URL encoded as per encode. Keys and values can be any term
-  that implements the Binary.Chars protocol (i.e. can be converted
-  to binary).
+  and returns a string of the form "k=v&k2=v2..." where keys and values are
+  URL encoded as per `encode/1`. Keys and values can be any term
+  that implements the `Binary.Chars` protocol (i.e. can be converted
+  to a binary).
   """
   def encode_query(l), do: Enum.map_join(l, "&", pair(&1))
 
@@ -61,7 +61,7 @@ defmodule URI do
   orddict with one entry for each key-value pair. Each key and value will be a
   binary. It also does percent-unescaping of both keys and values.
 
-  Use decoder/1 if you want to customize or iterate each value manually.
+  Use `query_decoder/1` if you want to iterate over each value manually.
   """
   def decode_query(q, dict // HashDict.new) when is_binary(q) do
     Enum.reduce query_decoder(q), dict, fn({ k, v }, acc) -> Dict.put(acc, k, v) end
@@ -150,14 +150,14 @@ defmodule URI do
   have different default ports. Sometimes the parsing
   of portions themselves are different. This parser
   is extensible via behavior modules. If you have a
-  module named URI.MYSCHEME with a function called
-  'parse' that takes a single argument, the generically
+  module named `URI.MYSCHEME` with a function called
+  `parse` that takes a single argument, the generically
   parsed URI, that function will be called when this
   parse function is passed a URI of that scheme. This
   allows you to build on top of what the URI library
-  currently offers. You also need to define default_port
-  which takes 0 arguments and returns the default port
-  for that particular scheme. Take a look at URI.HTTPS for an
+  currently offers. You also need to define `default_port`
+  which takes no arguments and returns the default port
+  for that particular scheme. Take a look at `URI.HTTPS` for an
   example of one of these extension modules.
   """
   def parse(s) when is_binary(s) do