مكتب المدينة

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()

التعليمات

لقد عملت في مكتب المدينة لبعض الوقت، وطوّرت مجموعة من الأدوات التي تُسرّع عملك اليومي، مثل ملء النماذج.

والآن ينضم إليك زميل جديد، وقد أدركت أن أدواتك قد لا تكون واضحة بذاتها. فهناك الكثير من الأعراف الغريبة في مكتبك، مثل ملء النماذج دائمًا بحروف كبيرة وتجنّب ترك الحقول فارغة.

لذلك قررت كتابة بعض التوثيق، حتى يسهل على زميلك الجديد أن يبدأ فورًا في استخدام أدواتك.

1. وثّق الغرض من أدوات النماذج

أضف توثيقًا إلى وحدة Form يصف الغرض منها. ينبغي أن يكون نصه:

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

2. وثّق ملء الحقول بقيم فارغة

أضف توثيقًا ومواصفة نوع إلى دالة Form.blanks/1. ينبغي أن يكون نص التوثيق:

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.

ينبغي أن توضّح مواصفة النوع أن الدالة تقبل وسيطًا واحدًا، وهو عدد صحيح غير سالب، وتُرجع سلسلة نصية.

3. وثّق تقسيم القيم إلى مصفوفات من الحروف الكبيرة

أضف توثيقًا ومواصفة نوع إلى دالة Form.letters/1. ينبغي أن يكون نص التوثيق:

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.

ينبغي أن توضّح مواصفة النوع أن الدالة تقبل وسيطًا واحدًا، وهو سلسلة نصية، وتُرجع مصفوفة من السلاسل النصية.

4. وثّق التحقق مما إذا كانت قيمة ما تناسب حقلًا بطول أقصى

أضف توثيقًا ومواصفة نوع إلى دالة Form.check_length/2. ينبغي أن يكون نص التوثيق:

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.

ينبغي أن توضّح مواصفة النوع أن الدالة تقبل وسيطين، سلسلة نصية وعددًا صحيحًا غير سالب، وتُرجع إحدى قيمتين محتملتين. فهي تُرجع إما ذرة :ok أو زوجًا مرتّبًا من عنصرين، الأول ذرة :error والثاني عدد صحيح موجب.

5. وثّق صيغ العناوين المختلفة

لسبب لا تعرفه، يستخدم النظام الداخلي لمكتب المدينة طريقتين مختلفتين لتمثيل العناوين: إما كخريطة أو كزوج مرتّب.

وثّق هذه الحقيقة عبر تعريف ثلاثة أنواع عامة مخصصة:

• address_map - خريطة بالمفاتيح :street و:postal_code و:city. يحمل كل مفتاح قيمة من النوع سلسلة نصية.
• address_tuple - زوج مرتّب بثلاث قيم: street وpostal_code وcity. كل قيمة من النوع سلسلة نصية. ميّز القيم بإعطائها أسماء في مواصفة النوع.
• address - يمكن أن يكون إما address_map أو address_tuple.

6. وثّق تنسيق العنوان

أضف توثيقًا ومواصفة نوع إلى دالة Form.format_address/1. ينبغي أن يكون نص التوثيق:

Formats the address as an uppercase multiline string.

ينبغي أن توضّح مواصفة النوع أن الدالة تقبل وسيطًا واحدًا، وهو عنوان، وتُرجع سلسلة نصية.