   This syntax reflects the fact the effective size is given by
   multiplying the size by the unit.
 
-  For floats, `size * unit` must result in 32 or 64, corresponding
-  to binary32 and binary64, respectively.
+  ### Modifiers
+
+  Some types have associated modifiers to clear up ambiguity in byte
+  representation.
+
+  Modifier             | Relevant Type(s)
+  -------------------- | ----------------
+  `signed`             | `integer`
+  `unsigned` (default) | `integer`
+  `little`             | `integer`, `utf16`, `utf32`
+  `big` (default)      | `integer`, `utf16`, `utf32`
+  `native`             | `integer`, `utf16`, `utf32`
+
+  ### Sign
+
+  Integers can be `signed` or `unsigned`, defaulting to `unsigned`.
+
+      iex> <<int::integer>> =  <<-100>>
+      <<156>>
+      iex> int
+      156
+      iex> <<int::integer-signed>> =  <<-100>>
+      <<156>>
+      iex> int
+      -100
+
+  `signed` and `unsigned` are only used for matching binaries (see below) and
+  are only used for integers.
+
+      iex> <<-100 :: signed, _rest :: binary>> = <<-100, "foo">>
+      <<156, 102, 111, 111>>
+
+  ### Endianness
+
+  Elixir has three options for endianness: `big`, `little`, and `native`.
+  The default is `big`. `native` is determined by the VM at startup.
+
+      iex> <<number::little-integer-size(16)>> = <<0, 1>>
+      <<0, 1>>
+      iex> number
+      256
+      iex> <<number::big-integer-size(16)>> = <<0, 1>>
+      <<0, 1>>
+      iex> number
+      1
+      iex> <<number::native-integer-size(16)>> = <<0, 1>>
+      <<0, 1>>
+      iex> number
+      256
+
+  ## Binary/Bitstring Matching
+
+  Binary matching is a powerful feature in Elixir that is useful for extracting
+  information from binaries as well as pattern matching.
+
+  Binary matching can be used by itself to extract information from binaries:
+
+      iex> <<"Hello, ", place::binary>> = "Hello, World"
+      "Hello, World"
+      iex> place
+      "World"
+
+  Or as a part of function definitions to pattern match:
+
+      defmodule ImageTyper
+        @png_signature <<137::size(8), 80::size(8), 78::size(8), 71::size(8),
+                      13::size(8), 10::size(8), 26::size(8), 10::size(8)>>
+        @jpg_signature <<255::size(8), 216::size(8)>>
+
+        def type(<<@png_signature, rest::binary>>), do: :png
+        def type(<<@jpg_signature, rest::binary>>), do: :jpg
+        def type(_), do :unknown
+      end
+
+  ### Performance & Optimizations
+
+  The Erlang compiler can provide a number of optimizations on binary creation
+  and matching. To see optimization output, set the `bin_opt_info` compiler
+  option:
+
+      `ERL_COMPILER_OPTIONS=bin_opt_info mix compile`
+
+  To learn more about specific optimizations and performance considerations,
+  check out
+  [Erlang's Efficiency Guide on handling binaries](http://www.erlang.org/doc/efficiency_guide/binaryhandling.html).
+
+
   """
   defmacro unquote(:<<>>)(args)
 

      iex> << 1, 2, 3 >>
      << 1, 2, 3 >>

  ## Bitstring types

  A bitstring is made of many segments. Each segment has a
  type, which defaults to integer:

      iex> <<1, 2, 3>>
      <<1, 2, 3>>

      iex> <<0, "foo">>
      <<0, 102, 111, 111>>

  Variables or any other type need to be explicitly tagged:

      iex> rest = "oo"
      iex> <<102, rest>>
