مستندات در

درباره‌ی مستندات

مستندات 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 را پیدا کنید.

می‌توانید بدون انتشار بسته در hex.pm، یک وب‌سایت مستندات برای پروژه‌ی خود بسازید که دقیقاً شبیه مستندات رسمی Elixir است. ابزاری که این کار را انجام می‌دهد 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 پس از نوشتن بخشی از اسم یک ماژول یا تابع، می‌توانید از گزینه‌ی تکمیل خودکار برای کشف ماژول‌ها و توابع موجود بهره ببرید.

IDEهای مدرن

بسیاری از IDEهای مدرن که از Elixir پشتیبانی می‌کنند می‌توانند مستندات و مشخصات نوع را تجزیه کنند و در پنجره‌های بازشوی مفیدی نمایش دهند، برای نمونه Visual Studio Code یا Intellij همراه با افزونه‌ی Elixir.

ماژول‌ها و توابع داخلی

اگر ماژول یا تابعی فقط برای استفاده‌ی داخلی در نظر گرفته شده باشد، می‌توانید آن را با @moduledoc false یا @doc false علامت‌گذاری کنید. آن ماژول‌ها و توابع در مستندات تولیدشده گنجانده نمی‌شوند. توجه کنید که این کار آن‌ها را خصوصی نمی‌کند. هنوز می‌توان آن‌ها را فراخوانی کرد و/یا import کرد. برای آشنایی با راه‌حل‌های ممکن برای این مشکل، مستندات رسمی درباره‌ی پنهان‌کردن ماژول‌ها و توابع داخلی را ببینید.