ডকস মধ্যে

ডকস সম্পর্কে

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 কমান্ড চালিয়ে (বা আপনার বর্তমান mix প্রজেক্টের সোর্স লোড করতে চাইলে iex -S 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.
# (...)

আংশিক মডিউল বা ফাংশনের নাম লেখার পর ট্যাব কী চাপলে অটোকমপ্লিটের সুবিধা নিয়ে কোন কোন মডিউল ও ফাংশন আছে তা খুঁজে বের করতে পারবেন।

আধুনিক IDE

Elixir সাপোর্ট করে এমন অনেক আধুনিক IDE ডকুমেন্টেশন ও টাইপস্পেক কাজের পপ-আপে দেখাতে পারে, যেমন Visual Studio Code বা Elixir প্লাগইনসহ Intellij।

ইন্টারনাল মডিউল ও ফাংশন

কোনো মডিউল বা ফাংশন যদি শুধু ইন্টারনাল ব্যবহারের জন্য হয়, তাহলে @moduledoc false বা @doc false দিয়ে সেটি চিহ্নিত করতে পারেন। ওই মডিউল ও ফাংশনগুলো জেনারেট হওয়া ডকুমেন্টেশনে যুক্ত হবে না। মনে রাখবেন, এতে সেগুলো প্রাইভেট হয়ে যায় না। সেগুলো এখনও ইনভোক ও/বা ইমপোর্ট করা যায়। এই সমস্যার সম্ভাব্য সমাধান জানতে ইন্টারনাল মডিউল ও ফাংশন লুকানোর অফিসিয়াল ডকুমেন্টেশন দেখুন।