Stadtbüro

defmodule String do
  @moduledoc """
  Strings in Elixir are UTF-8 encoded binaries.
  """

  @doc """
  Converts all characters in the given string to uppercase according to `mode`.

  ## Examples

      iex> String.upcase("abcd")
      "ABCD"

      iex> String.upcase("olá")
      "OLÁ"
  """
  def upcase(string, mode \\ :default)
end

@spec longer_than?(String.t(), non_neg_integer()) :: boolean()
def longer_than?(string, length), do: String.length(string) > length

@spec to_hex({hue :: integer, saturation :: integer, lightness :: integer}) :: String.t()

@type color :: {hue :: integer, saturation :: integer, lightness :: integer}

@spec to_hex(color()) :: String.t()

Anleitung

Du arbeitest seit einer Weile im Stadtbüro und hast eine Reihe von Tools entwickelt, die deine tägliche Arbeit beschleunigen, zum Beispiel das Ausfüllen von Formularen.

Jetzt kommt eine neue Kollegin zu dir ins Team, und dir ist aufgefallen, dass deine Tools vielleicht nicht selbsterklärend sind. In deinem Büro gibt es viele seltsame Konventionen, zum Beispiel Formulare immer in Großbuchstaben auszufüllen und Felder nicht leer zu lassen.

Du beschließt, eine Dokumentation zu schreiben, damit deine neue Kollegin direkt einsteigen und deine Tools nutzen kann.

1. Dokumentiere den Zweck der Formular-Tools

Füge dem Modul Form eine Dokumentation hinzu, die seinen Zweck beschreibt. Sie sollte so lauten:

A collection of loosely related functions helpful for filling out various forms at the city office.

2. Dokumentiere das Ausfüllen von Feldern mit leeren Werten

Füge der Funktion Form.blanks/1 eine Dokumentation und eine Typspezifikation hinzu. Die Dokumentation sollte so lauten:

Generates a string of a given length.

This string can be used to fill out a form field that is supposed to have no value.
Such fields cannot be left empty because a malicious third party could fill them out with false data.

Die Typspezifikation sollte erklären, dass die Funktion ein einziges Argument akzeptiert, eine nicht-negative Ganzzahl, und einen String zurückgibt.

3. Dokumentiere das Aufteilen von Werten in Listen aus Großbuchstaben

Füge der Funktion Form.letters/1 eine Dokumentation und eine Typspezifikation hinzu. Die Dokumentation sollte so lauten:

Splits the string into a list of uppercase letters.

This is needed for form fields that don't offer a single input for the whole string,
but instead require splitting the string into a predefined number of single-letter inputs.

Die Typspezifikation sollte erklären, dass die Funktion ein einziges Argument akzeptiert, einen String, und eine Liste von Strings zurückgibt.

4. Dokumentiere die Prüfung, ob ein Wert in ein Feld mit maximaler Länge passt

Füge der Funktion Form.check_length/2 eine Dokumentation und eine Typspezifikation hinzu. Die Dokumentation sollte so lauten:

Checks if the value has no more than the maximum allowed number of letters.

This is needed to check that the values of fields do not exceed the maximum allowed length.
It also tells you by how much the value exceeds the maximum.

Die Typspezifikation sollte erklären, dass die Funktion zwei Argumente akzeptiert, einen String und eine nicht-negative Ganzzahl, und einen von zwei möglichen Werten zurückgibt. Sie gibt entweder das Atom :ok zurück oder ein 2-Tupel, dessen erstes Element das Atom :error ist und dessen zweites eine positive Ganzzahl ist.

5. Dokumentiere verschiedene Adressformate

Aus dir unbekannten Gründen verwendet das interne System des Stadtbüros zwei verschiedene Arten, Adressen darzustellen: entweder als Map oder als Tupel.

Dokumentiere diese Tatsache, indem du drei eigene öffentliche Typen definierst:

• address_map: eine Map mit den Schlüsseln :street, :postal_code und :city. Jeder Schlüssel enthält einen Wert vom Typ String.
• address_tuple: ein Tupel mit drei Werten, nämlich street, postal_code und city. Jeder Wert ist vom Typ String. Unterscheide die Werte, indem du ihnen in der Typspezifikation Namen gibst.
• address: kann entweder eine address_map oder eine address_tuple sein.

6. Dokumentiere das Formatieren der Adresse

Füge der Funktion Form.format_address/1 eine Dokumentation und eine Typspezifikation hinzu. Die Dokumentation sollte so lauten:

Formats the address as an uppercase multiline string.

Die Typspezifikation sollte erklären, dass die Funktion ein Argument akzeptiert, eine Adresse, und einen String zurückgibt.