डॉक्स में

डॉक्स के बारे में

Elixir का डॉक्युमेंटेशन:

• यह पहले दर्जे का नागरिक है।
• यह Markdown में लिखा जाता है।
• इसे खास मॉड्यूल एट्रिब्यूट इस्तेमाल करके जोड़ा जाता है।
• मल्टीलाइन स्ट्रिंग के लिए यह आम तौर पर हेरडॉक सिंटैक्स इस्तेमाल करता है।

डॉक्युमेंटेशन के लिए इस्तेमाल होने वाले मॉड्यूल एट्रिब्यूट:

• @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.
# (...)

मॉड्यूल या फंक्शन का आधा नाम लिखकर टैब कुंजी दबाने पर आप ऑटोकंपलीट की सुविधा से उपलब्ध मॉड्यूल और फंक्शन खोज सकते हैं।

आधुनिक IDE

Elixir को सपोर्ट करने वाले कई आधुनिक IDE डॉक्युमेंटेशन और टाइपस्पेक को काम के पॉप-अप में पार्स और प्रदर्शित कर सकते हैं, जैसे Visual Studio Code या Elixir प्लगइन वाला Intellij।

इंटरनल मॉड्यूल और फंक्शन

अगर कोई मॉड्यूल या फंक्शन सिर्फ इंटरनल उपयोग के लिए है, तो आप उसे @moduledoc false या @doc false से चिह्नित कर सकते हैं। वे मॉड्यूल और फंक्शन बनने वाले डॉक्युमेंटेशन में शामिल नहीं होंगे। ध्यान रखिए कि इससे वे प्राइवेट नहीं हो जाते। उन्हें अब भी कॉल और/या इम्पोर्ट किया जा सकता है। इस समस्या के संभावित हल जानने के लिए इंटरनल मॉड्यूल और फंक्शन छिपाने के बारे में आधिकारिक डॉक्युमेंटेशन देखिए।