 
   When disabled, it behaves as usual and it will ignore
   any further `next_break_fits/2` instruction.
+
+  ## Examples
+
+  This is used by Elixir's code formatter to avoid breaking
+  code at some specific locations. For example, consider this
+  code:
+
+      some_function_call(%{..., key: value, ...})
+
+  Now imagine that this code does not fit its line. The code
+  formatter introduces breaks inside `(` and `)` and inside
+  `%{` and `}`. Therefore the document would break as:
+
+      some_function_call(
+        %{
+          ...,
+          key: value,
+          ...
+        }
+      )
+
+  The formatter wraps the algebra document representing the
+  map in `next_break_fits/1` so the code is formatted as:
+
+      some_function_call(%{
+        ...,
+        key: value,
+        ...
+      })
+
   """
   @spec next_break_fits(t) :: doc_fits
   def next_break_fits(doc, mode \\ @next_break_fits) when is_doc(doc) do

  end

  @doc """
  Introduces a flex break.

  A flex break still causes a group to break, like
  a regular break, but it is re-evaluated when the
  documented is processed.

  This function is used by `container_doc/4` and friends
  to the maximum number of entries on the same line.
  """
  @spec flex_break(binary) :: doc_break
  def flex_break(string \\ " ") when is_binary(string) do

  end

  @doc ~S"""
  Returns a break document based on the given `string`.

  This break can be rendered as a linebreak or as the given `string`,
  depending on the `mode` of the chosen layout.
