Guidedog / दस्तावेज़ 0.2.0

Odin के दस्तावेज़ बनाना¶

Odin डोमेन पैकेज, प्रोसीजर, प्रकार और सदस्य को नाम वाले लक्ष्य देता है। Guidedog Odin सोर्स पार्स करके API पेज भी बनाता है। वह कंपाइलर या पैकेज नहीं चलाता। बने सिग्नेचर के साथ भी उपयोगी अनुबंध चाहिए।

ऑब्जेक्ट का वर्णन¶

Python मॉड्यूल की तरह पैकेज आगे के विवरण का संदर्भ है:

.. odin:package:: core:strings
   :synopsis: Procedures to manipulate UTF-8 encoded strings.
   :imports: rt=base:runtime

.. odin:procedure:: @(require_results) clone :: proc(s: string, allocator := context.allocator) -> (res: string, err: rt.Allocator_Error) #optional_allocator_error

   Clones a string.

   :param s: The string to be cloned.
   :result res: The cloned string.
   :result err: An allocator error, or ``nil``.

.. odin:struct:: Builder :: struct

   A dynamic byte buffer.

   .. odin:field:: buf: [dynamic]byte

सिग्नेचर Odin घोषणाओं की तरह एक पंक्ति में लिखे और वैसे ही दिखाए जाते हैं। नीचे के उदाहरण ऐसे दिखते हैं:

shapes.Kind :: enum u8

Circle = 1

@(require_results) shapes.area :: proc(side: f32, scale: f32 = 1) -> (a: f32, ok: bool) #optional_ok

एक वर्ग को मापता है।

पैरामीटर:

side – इसकी भुजा।

रिटर्न:

a – इसका क्षेत्रफल।
ok – इसका प्रकार ज्ञात है या नहीं।

निर्देश और उनके स्वीकार किए सिग्नेचर:

odin:package और odin:currentpackage: core:fmt या प्रोजेक्ट के मूल के नीचे readers/sphinx जैसा पथ दें। ऑब्जेक्ट का नाम पैकेज इंपोर्ट पथ से है: core:fmt.println। odin:currentpackage बिना लक्ष्य बनाए संदर्भ बदलता है; None उसे हटाता है। विकल्प: :synopsis:, :platform:, :deprecated:, :no-index: और :imports:। अंतिम में सिग्नेचर के इंपोर्ट उपनाम alias=package जोड़ों (gd=core rst=readers/rst) में हैं; gd.Node_Id तब core.Node_Id से लिंक होता है। :private: निजी प्रकार और प्रोसीजर समूह के निजी सदस्य (State Rules catalog_text) देता है। वर्णन न होने से सिग्नेचर इन्हें पाठ दिखाता है। बने पेज इन्हें स्वतः सूचीबद्ध करते हैं।
odin:procedure (या odin:proc): name :: proc(params) -> results में नाम से पहले गुण (@(require_results)), proc से पहले #force_inline, कॉल नियम (proc "c" (...)), डिफ़ॉल्ट तर्क (x := 1, x: int = 1), $T बहुरूपी तर्क, .. परिवर्तनीय तर्क, using, #c_vararg, नाम वाले परिणाम, टैग (#optional_ok) और where खंड स्वीकार हैं। name(params) -> results इसका छोटा रूप है।
odin:procgroup: name :: proc{a, b}: हर सदस्य अपने प्रोसीजर से लिंक होता है।
odin:struct, odin:union, odin:enum, odin:bitset, odin:bitfield, odin:type: Name :: struct($T: typeid) #packed, Name :: union #no_nil {A, B}, Name :: enum u8, Name :: bit_set[Flag; u8], Name :: bit_field u32। odin:type में distinct प्रकार और उपनाम (Handle :: distinct uintptr, Callback :: proc(x: int) -> bool) हैं। प्रकार की सामग्री में सदस्य आते हैं।
odin:field और odin:enumerator: प्रकार के भीतर name: Type के साथ टैग (name: string `json:"n"`) या बिट आकार (low: u8 | 3), और Name या Name = 3 हैं। इनके नाम Type.member होते हैं।
odin:const, odin:var, odin:foreign: NAME :: 64 या NAME : int : 64; name: Type, name := value या name: Type = value; विदेशी इंपोर्ट के लिए libc "system:c"।

हर ऑब्जेक्ट Sphinx के :no-index:, :no-index-entry:, :no-contents-entry: और :no-typesetting: लेता है। अपने विकल्प हैं :package: (दूसरे पैकेज में वर्णन), :private: और :deprecated: message (सिग्नेचर में न हों तो @(private) और @(deprecated="message")), :availability: Windows, Linux (पहली पंक्ति में उपलब्धता), :foreign: libc (foreign ब्लॉक का प्रोसीजर)। कई सिग्नेचर पंक्तियाँ अलग लक्ष्यों पर एक ऑब्जेक्ट दिखाती हैं; ID और सूचकांक केवल पहली को मिलते हैं।

प्रकार की जगह के नाम पहले सिग्नेचर के पैकेज और प्रकार में, फिर लिखे रूप में खोजकर लिंक होते हैं। अंतर्निहित प्रकार (int, string, rawptr, typeid, any आदि), कुंजीशब्द, बहुरूपी नाम ($T और आगे T, बाहरी प्रकार सहित), ऐरे लंबाई, डिफ़ॉल्ट, स्थिरांक, टैग और where खंड केवल लिखे रूप में दिखते हैं, लिंक नहीं।

रोल और ID¶

:odin:pkg:, :odin:proc:, :odin:type: (struct, union, enum, bit set, bit field आदि), :odin:const:, :odin:var:, :odin:field:, :odin:enumerator: और :odin:obj: (कोई भी) लिंक देते हैं। Python की तरह ~ अंतिम हिस्सा दिखाता है (:odin:proc:`~core:fmt.println` में println); प्रारंभिक . किसी ऑब्जेक्ट नाम का अंत खोजता है। खोज संदर्भ के प्रकार और पैकेज, फिर मूल नाम, फिर पथ के : या / के बाद होती है। fmt.println को core:fmt.println और sphinx.Config को readers/sphinx.Config मिलता है, जैसे Odin अंतिम पथ नाम लेता है। :imports: उपनाम पहले देखा जाता है। default-domain:: odin या primary_domain = "odin" में odin: छोड़ सकते हैं।

ID Sphinx का make_id है, odin- और पूरे नाम पर: odin-core-fmt.println, odin-readers-sphinx.Config.docname। Python ID की तरह केस और बिंदु रहते हैं; पथ का : और / हाइफ़न बनते हैं। ID पढ़ने योग्य, स्थिर और समान अंतिम नाम के पैकेज में अलग हैं। पैकेज ID odin-package- तथा पथ है। सूचकांक "println (procedure in core:fmt)" जैसा है। objects.inv सभी ऑब्जेक्ट odin डोमेन और प्रकार (odin:procedure, odin:struct, odin:field आदि) में रखता है; Sphinx मॉड्यूल की तरह पैकेज पहले हैं।

सामग्री के सूचना फ़ील्ड दूसरे डोमेन की तरह समूहित होते हैं: :param name: (:type name: सहित), नाम वाले परिणाम का :result name:, :returns: और :rtype:।

स्रोत से बनाना¶

सोर्स फ़ोल्डर के सापेक्ष पैकेज की जगह बताएँ:

odin_autoapi_dirs = ["../src"]
odin_collections = {core = "/usr/local/lib/odin/core"}  # optional

odin_autoapi_dirs के नीचे पैकेज सापेक्ष पथ से नाम पाता है (src/shapes/round का shapes/round)। संग्रह में Odin इंपोर्ट नाम (core:strings) है। निर्माण निर्देश autodoc की तरह चलते हैं:

.. odin:autopackage:: shapes
   :members:
   :undoc-members:
   :member-order: groupwise

.. odin:autoproc:: shapes.area
.. odin:autotype:: Shape

odin:autopackage पैकेज और टिप्पणी लिखता है; :members: पर सभी या चुनी घोषणाएँ भी। odin:autoproc, odin:autoprocgroup, odin:autotype, odin:autoconst, odin:autovar वर्तमान पैकेज नाम या package.name की एक घोषणा देते हैं। विकल्प: :members:, :undoc-members:, :private-members: (सामान्यतः हटे @(private)), :exclude-members:, :member-order: (डिफ़ॉल्ट source में फ़ाइल नाम फिर स्थान; alphabetical; groupwise के शीर्षक "Types", "Procedures", "Procedure groups", "Constants", "Variables", "Foreign imports") और :no-index:।

दस्तावेज़ टिप्पणियाँ घोषणा के ठीक ऊपर // पंक्तियाँ या /* */ ब्लॉक, तथा फ़ील्ड या enum सदस्य के अंत की टिप्पणी हैं। ये सादा पाठ हैं, जो इस तरह reStructuredText बनता है:

अनुच्छेद अनुच्छेद रहते हैं; - item पंक्तियाँ सूची रहती हैं।
खाली पंक्ति या कोलन वाली पंक्ति (Example:) के बाद टैब या स्पेस से इंडेंट ब्लॉक code-block:: odin है; Output: के बाद text है। अनुच्छेद पंक्ति के ठीक बाद के पाठ से अधिक इंडेंट पंक्ति उसी को आगे बढ़ाती है।
Inputs: के बाद - name: text से :param name: फ़ील्ड और Returns: से :result name: बनते हैं; नाम न हो तो :returns:। यह Odin कोर लाइब्रेरी का रूप है।
NOTE: या WARNING: से शुरू पंक्ति नोट या चेतावनी बनती है।
`code` लिटरल पाठ है। reStructuredText के मार्कअप वाले दूसरे अक्षर (*, |, शब्द के अंत का _ आदि) एस्केप होते हैं, इसलिए टिप्पणी जैसी लिखी है वैसी दिखती है और चेतावनी नहीं आती।

API पृष्ठ¶

odin_autoapi_dirs देने पर हर पैकेज का पेज पढ़ने के दौरान बनता है, sphinx-autoapi की तरह। api/shapes में odin_autoapi_options के साथ odin:autopackage:: shapes और api/index में पैकेज व सारांश हैं। पेज प्रोजेक्ट दस्तावेज़ हैं: toctree, खोज, सामान्य सूचकांक, singlehtml और PDF में आते हैं, पर सोर्स फ़ोल्डर में नहीं लिखे जाते। सेटिंग:

odin_autoapi_dirs: पेज पाने वाले पैकेज के फ़ोल्डर, सोर्स के सापेक्ष। केवल इनके और odin_collections के नीचे की फ़ाइलें पढ़ी जाती हैं। बाहर जाता लिंक अस्वीकार है।
odin_collections: core:strings जैसे निर्देश तर्कों के लिए संग्रह नाम और फ़ोल्डर की तालिका। इन पैकेजों के पेज नहीं बनते।
odin_autoapi_root: पेज का फ़ोल्डर; डिफ़ॉल्ट "api"। स्रोत में समान नाम का दस्तावेज़ हो तो वही रहता है और चेतावनी मिलती है।
odin_autoapi_options: डिफ़ॉल्ट ["members", "undoc-members"]; private-members जोड़ा जा सकता है।
odin_autoapi_member_order: "source" (डिफ़ॉल्ट), "alphabetical" या "groupwise"।
odin_autoapi_add_toctree_entry: true (डिफ़ॉल्ट): api/index मूल दस्तावेज़ के पहले toctree में जुड़ता है।
odin_autoapi_generate_api_docs: true (डिफ़ॉल्ट); false में फ़ोल्डर केवल निर्देशों के लिए पढ़े जाते हैं।

जिस पैकेज का दस्तावेज़ नहीं, उसके प्रकार (core:io.Writer) लिंक नहीं होते। -n में nitpick_ignore_regex = [["odin:type", "(core|base):.*"]] से चेतावनी दबाएँ। Guidedog का docs/api भी ऐसे बनता है।

प्लैटफ़ॉर्म¶

पैकेज के Odin लक्ष्यों का दस्तावेज़ उसी के फ़ाइल नियमों से बनता है। *_windows.odin, *_linux_arm64.odin, *_amd64.odin केवल संबंधित लक्ष्य हैं। #+build linux, darwin, #+build !windows और पुराने //+build दायरा घटाते हैं। फ़ाइल स्तर का when ODIN_OS == .Windows केवल ODIN_OS व ODIN_ARCH तुलना करे तो शाखा उसके लक्ष्य और else बाकी हैं। *_test.odin और #+ignore हटते हैं। सब लक्ष्यों की घोषणा एक बार; कुछ की "Availability: Windows" सहित। अलग सिग्नेचर अलग लक्ष्य सहित दिखते हैं; ID पहले का है। सीमित लक्ष्य वाला पैकेज :platform: बताता है।

दोबारा बिल्ड करना¶

पेज द्वारा पढ़ी हर Odin फ़ाइल उसकी निर्भरता है। सोर्स बदलने पर अगली बिल्ड केवल उस पैकेज के पेज फिर पढ़ती है। पैकेज जुड़ने, हटने या सारांश बदलने पर सूचकांक फिर पढ़ा जाता है। guidedog serve HTML देने से पहले odin_autoapi_dirs और odin_collections का बदलाव समय देखता है। संपादन के बाद ब्राउज़र रिफ़्रेश करें।

सीमाएँ¶

सोर्स केवल पार्स होता है, संकलन या प्रकार जाँच नहीं। प्रकार और स्थिरांक जैसे लिखे हैं वैसे दिखते हैं; 100 अक्षर से बड़ा मान हटता है। अनुमान नहीं होता। A :: B का प्रकार या स्थिरांक नाम से तय है: बड़े अक्षर से शुरू लेकिन पूरी तरह बड़े अक्षर नहीं, या अंतर्निहित प्रकार, तो प्रकार है।
when में ODIN_OS और ODIN_ARCH की तुलना के अलावा शर्तें नहीं जाँची जातीं; दोनों शाखाएँ लिखी जाती हैं।
निजी प्रकार का नाम पाठ दिखता है क्योंकि :private-members: के बिना उसकी प्रविष्टि नहीं। बना पैकेज उन्हें :private: में रखता है, इसलिए -n रिपोर्ट नहीं करता।
core:odin/parser दोनों #optional_ok और where वाला प्रोसीजर अस्वीकार करता है। फ़ाइल की सूचना दी जाती है और पढ़ा जा सका हिस्सा दस्तावेज़ बनता है।
गहरे कोड में Odin पार्सर बहुत स्टैक लेता है; कुछ सौ कोष्ठक थ्रेड स्टैक भर सकते हैं। वास्तविक कोड से कहीं गहरी फ़ाइल (लगभग 50 कोष्ठक या प्रकार स्तर, या एक कड़ी में करीब हज़ार else) odin.autodoc.nesting चेतावनी से हटती है। शेष पैकेज लिखा जाता है। when के &&, ||, ! 64 स्तर तक जाँचे जाते हैं; अधिक पर बिना मूल्यांकन माना जाता है।