التوثيق في

نبذة عن التوثيق

توثيق Elixir:

• عنصر من الدرجة الأولى.
• يُكتب بـMarkdown.
• يُضاف باستخدام سمات وحدة خاصة.
• يستخدم عادةً صيغة heredoc للسلاسل النصية متعددة الأسطر.

سمات الوحدة المستخدمة في التوثيق:

• @moduledoc - يصف وحدة، ويظهر في السطر الأول من الوحدة.
• @doc - يصف دالة، ويظهر مباشرة فوق تعريف الدالة ومواصفة نوعها.
• @typedoc- يصف نوعًا مخصصًا، ويظهر مباشرة فوق تعريف النوع.

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

  @typedoc """
  A UTF-8 encoded binary.
  """
  @type t :: binary

  @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

التوثيق مقابل تعليقات الكود

يتعامل Elixir مع التوثيق وتعليقات الكود كمفهومين مختلفين.

التوثيق عقد صريح بينك وبين مستخدمي واجهة API العامة لديك (وهو يشمل أيضًا زملاءك في العمل وأنت في المستقبل). وقد تتاح لهؤلاء المستخدمين إمكانية الوصول إلى الكود المصدري وقد لا تتاح، لذلك يشرح التوثيق كيفية استخدام الكود.

أما تعليقات الكود فهي موجّهة إلى المطورين الذين يقرؤون الكود المصدري. وهي مفيدة لتدوين الملاحظات، وشرح تفاصيل التنفيذ، والإشارة إلى فرص التحسين، وما إلى ذلك.

ولأن التوثيق مخصص لوصف واجهة API العامة لكودك، فإن محاولة إضافة سمة @doc إلى دالة خاصة ستؤدي إلى تحذير عند التصريف. ولشرح الدوال الخاصة، استخدم تعليقات الكود بدلًا من ذلك.

warning: defp do_check_length/2 is private, @doc attribute is always discarded for private functions/macros/types
  lib/form.ex:33: Form.do_check_length/2

الاطلاع على التوثيق

هناك طرق عديدة ومختلفة للوصول إلى توثيق مشروع Elixir.

hexdocs.pm وExDoc

hex.pm مستودع حزم لكلٍّ من Elixir وErlang. وكل حزمة تُنشر على hex.pm يُنشر توثيقها تلقائيًا على hexdocs.pm. وهناك يمكنك أن تجد توثيق جميع مكتبات Elixir المفضلة لديك، وكذلك توثيق Elixir الرسمي نفسه.

يمكنك إنشاء موقع توثيق لمشروعك يبدو تمامًا مثل توثيق Elixir الرسمي دون الحاجة إلى نشر حزمة على hex.pm. والأداة التي تفعل ذلك تُسمى ExDoc. وسينتج ExDoc ملفات HTML يمكنك تصفحها من نظام ملفاتك المحلي.

احرص على اتباع التوصيات الرسمية لكتابة التوثيق لضمان أفضل النتائج عند استخدام ExDoc.

المساعد h في IEx

يمكنك الوصول إلى توثيق المكتبة القياسية، وكذلك أي مكتبة ثبّتها ومشروع Elixir الخاص بك، مباشرةً من حاسوبك.

إذا كان Elixir مثبّتًا على حاسوبك، فيمكنك استخدامه في الوضع التفاعلي بتشغيل الأمر iex (أو iex -S mix إذا أردت تحميل مصدر مشروع mix الحالي لديك).

في iex، يمكنك كتابة h، متبوعًا بمسافة واسم وحدة أو اسم دالة، لقراءة توثيقه.

iex()> h String.upcase/1
# def upcase(string, mode \\ :default)
#
# Converts all characters in the given string to uppercase according to mode.
# (...)

وبالضغط على مفتاح Tab بعد كتابة جزء من اسم وحدة أو دالة، يمكنك الاستفادة من خاصية الإكمال التلقائي لاكتشاف الوحدات والدوال المتاحة.

بيئات التطوير المتكاملة الحديثة

تستطيع العديد من بيئات التطوير المتكاملة الحديثة التي تدعم Elixir تحليل التوثيق ومواصفات الأنواع وعرضها في نوافذ منبثقة مفيدة، مثل Visual Studio Code أو Intellij مع إضافة Elixir.

الوحدات والدوال الداخلية

إذا كانت وحدة أو دالة مخصصة للاستخدام الداخلي فقط، فيمكنك تعليمها بـ @moduledoc false أو @doc false. ولن تُضمَّن هذه الوحدات والدوال في التوثيق المُنشأ. لاحظ أن ذلك لا يجعلها خاصة، فلا يزال من الممكن استدعاؤها و/أو استيرادها. راجع التوثيق الرسمي حول إخفاء الوحدات والدوال الداخلية للتعرّف على الحلول المحتملة لهذه المشكلة.