Documentation

Accessing Documentation

يمكن الوصول إلى الوثائق في REPL أو في IJulia عن طريق كتابة ? متبوعًا باسم دالة أو ماكرو، ثم الضغط على Enter. على سبيل المثال،

?cos
?@time
?r""

سوف تظهر الوثائق للدالة أو الماكرو أو ماكرو السلسلة المعنية على التوالي. توفر معظم بيئات جوليا وسيلة للوصول إلى الوثائق مباشرة:

• VS Code يظهر الوثائق عند تمرير المؤشر فوق اسم الدالة. يمكنك أيضًا استخدام لوحة جوليا في الشريط الجانبي للبحث عن الوثائق.
• في Pluto، افتح لوحة "المستندات الحية" في الزاوية السفلى اليمنى.
• في Juno باستخدام Ctrl-J, Ctrl-D سيظهر الوثائق للكائن تحت المؤشر.

Docs.hasdoc(module, name)::Bool يخبر ما إذا كان للاسم سلسلة توثيق. Docs.undocumented_names(module; all) تُرجع الأسماء غير الموثقة في وحدة.

Writing Documentation

تتيح جوليا لمطوري الحزم والمستخدمين توثيق الدوال والأنواع وغيرها من الكائنات بسهولة من خلال نظام توثيق مدمج.

الصيغة الأساسية بسيطة: أي سلسلة تظهر مباشرة قبل كائن (دالة، ماكرو، نوع أو مثيل) سيتم تفسيرها على أنها توثق ذلك (تسمى هذه سلاسل الوثائق). لاحظ أنه لا يمكن أن تتدخل أي أسطر فارغة أو تعليقات بين سلسلة الوثائق والكائن الموثق. إليك مثال أساسي:

"Tell whether there are too foo items in the array."
foo(xs::Array) = ...

تُفسر الوثائق على أنها Markdown، لذا يمكنك استخدام المسافات البادئة وأقواس التعليمات البرمجية لتحديد أمثلة التعليمات البرمجية من النص. من الناحية الفنية، يمكن ربط أي كائن بأي كائن آخر كبيانات وصفية؛ يحدث أن يكون Markdown هو الافتراضي، ولكن يمكن للمرء إنشاء ماكرو نصي آخر وتمريره إلى ماكرو @doc بنفس القدر.

بالطبع! يمكنك لصق المحتوى الذي ترغب في ترجمته إلى العربية وسأقوم بذلك.

"""
    bar(x[, y])

Compute the Bar index between `x` and `y`.

If `y` is unspecified, compute the Bar index between all pairs of columns of `x`.

# Examples
```julia-repl
julia> bar([1, 2], [1, 2])
1
```
"""
function bar(x, y) ...

كما في المثال أعلاه، نوصي باتباع بعض التقاليد البسيطة عند كتابة الوثائق:

1. دائمًا اعرض توقيع الدالة في أعلى الوثائق، مع مسافة بادئة من أربعة مسافات بحيث يتم طباعته ككود جوليا.

   يمكن أن يكون هذا مطابقًا للتوقيع الموجود في كود جوليا (مثل mean(x::AbstractArray))، أو شكل مبسط. يجب تمثيل الوسائط الاختيارية بقيمها الافتراضية (أي f(x, y=1)) عند الإمكان، مع اتباع بناء جملة جوليا الفعلي. يجب وضع الوسائط الاختيارية التي لا تحتوي على قيمة افتراضية بين قوسين (أي f(x[, y]) و f(x[, y[, z]])). حل بديل هو استخدام عدة أسطر: واحد بدون وسائط اختيارية، والآخر(ون) معهما. يمكن أيضًا استخدام هذا الحل لتوثيق عدة طرق ذات صلة لدالة معينة. عندما تقبل دالة العديد من الوسائط الرئيسية، يجب تضمين عنصر نائب <keyword arguments> فقط في التوقيع (أي f(x; <keyword arguments>))، وإعطاء القائمة الكاملة تحت قسم # Arguments (انظر النقطة 4 أدناه).

2. تتضمن جملة واحدة تصف ما تفعله الدالة أو ما يمثله الكائن بعد كتلة التوقيع المبسطة. إذا لزم الأمر، قدم مزيدًا من التفاصيل في فقرة ثانية، بعد فراغ.

   يجب أن تستخدم الجملة ذات السطر الواحد صيغة الأمر ("افعل هذا"، "أعد ذلك") بدلاً من الشخص الثالث (لا تكتب "يعود الطول...") عند توثيق الوظائف. يجب أن تنتهي بنقطة. إذا لم يكن من السهل تلخيص معنى وظيفة ما، فقد يكون من المفيد تقسيمها إلى أجزاء قابلة للتكوين بشكل منفصل (يجب ألا يُعتبر هذا مطلبًا مطلقًا لكل حالة على حدة).

3. لا تكرر نفسك.

   نظرًا لأن اسم الدالة محدد من خلال التوقيع، فلا حاجة لبدء الوثائق بعبارة "الدالة bar...": اذهب مباشرة إلى النقطة. وبالمثل، إذا كان التوقيع يحدد أنواع المعاملات، فإن ذكرها في الوصف يعتبر زائداً.

4. فقط قدم قائمة بالوسائط عند الضرورة القصوى.

   للوظائف البسيطة، غالبًا ما يكون من الواضح ذكر دور المعاملات مباشرة في وصف غرض الوظيفة. ستكرر قائمة المعاملات فقط المعلومات المقدمة في مكان آخر. ومع ذلك، فإن تقديم قائمة بالمعاملات يمكن أن يكون فكرة جيدة للوظائف المعقدة التي تحتوي على العديد من المعاملات (وبشكل خاص معاملات الكلمات الرئيسية). في هذه الحالة، قم بإدراجها بعد الوصف العام للوظيفة، تحت عنوان # Arguments، مع نقطة - واحدة لكل معامل. يجب أن تذكر القائمة الأنواع والقيم الافتراضية (إن وجدت) للمعاملات:

   ```julia """ ...

   Arguments

   • n::Integer: the number of elements to compute.
   • dim::Integer=1: the dimensions along which to perform the computation.

   ... """ ```

5. قدم تلميحات للوظائف ذات الصلة.

   أحيانًا توجد وظائف ذات وظائف ذات صلة. لزيادة إمكانية الاكتشاف، يرجى تقديم قائمة قصيرة من هذه في فقرة انظر أيضًا.

   See also [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref).

6. Include any code examples in an # Examples section.

   يجب أن تكون الأمثلة، كلما كان ذلك ممكنًا، مكتوبة كـ doctests. doctest هو كتلة كود محاطة (انظر Code blocks) تبدأ بـ ```jldoctest وتحتوي على أي عدد من مطالبات julia> مع المدخلات والمخرجات المتوقعة التي تحاكي REPL الخاص بـ Julia.

   !!! note تم تفعيل اختبارات الوثائق بواسطة Documenter.jl. لمزيد من الوثائق التفصيلية، راجع وثائق Documenter's manual.

على سبيل المثال في التعليق التوضيحي التالي، يتم تعريف متغير `a` والنتيجة المتوقعة، كما تظهر في REPL لجوليا، تظهر بعد ذلك:

````julia
"""
Some nice documentation here.

# Examples
```jldoctest
julia> a = [1 2; 3 4]
2×2 Array{Int64,2}:
 1  2
 3  4
```
"""
````

!!! warning
    يجب تجنب استدعاء `rand` وغيرها من الدوال المتعلقة بتوليد الأرقام العشوائية في اختبارات الوثائق (doctests) لأنها لن تنتج مخرجات متسقة خلال جلسات جوليا المختلفة. إذا كنت ترغب في عرض بعض الوظائف المتعلقة بتوليد الأرقام العشوائية، فإن إحدى الخيارات هي بناء كائن RNG خاص بك وتحديد البذور الخاصة به بشكل صريح (انظر [`Random`](@ref Random-Numbers)) وتمريره إلى الدوال التي تقوم باختبارها.

    حجم كلمة نظام التشغيل ([`Int32`](@ref) أو [`Int64`](@ref)) بالإضافة إلى اختلافات فاصل المسار (`/` أو `\`) ستؤثر أيضًا على إمكانية إعادة إنتاج بعض اختبارات الوثائق.

    لاحظ أن الفراغات في اختبارك الوثائقي مهمة! سيفشل اختبار الوثائق إذا قمت بخطأ في محاذاة ناتج الطباعة الجميل لمصفوفة، على سبيل المثال.


يمكنك بعد ذلك تشغيل `make -C doc doctest=true` لتشغيل جميع اختبارات الوثائق في دليل جوليا ووثائق واجهة برمجة التطبيقات، مما سيضمن أن مثالك يعمل.

لإظهار أن نتيجة الإخراج مقطوعة، يمكنك كتابة `[...]` في السطر الذي يجب أن يتوقف عنده الفحص. هذا مفيد لإخفاء تتبع المكدس (الذي يحتوي على مراجع غير دائمة لأسطر من كود جوليا) عندما يظهر اختبار الوثائق أن استثناءً قد تم طرحه، على سبيل المثال:

````julia
```jldoctest
julia> div(1, 0)
ERROR: DivideError: integer division error
[...]
```
````

يجب كتابة الأمثلة التي لا يمكن اختبارها داخل كتل التعليمات البرمجية المحاطة بـ ````` ```julia````` حتى يتم تمييزها بشكل صحيح في الوثائق الناتجة.

!!! tip
    حيثما أمكن، يجب أن تكون الأمثلة **مستقلة** و**قابلة للتشغيل** حتى يتمكن القراء من تجربتها دون الحاجة إلى تضمين أي تبعيات.

1. استخدم العلامات المقتبسة لتحديد الشيفرة والمعادلات.

   يجب أن تظهر معرفات جوليّا ومقتطفات الشيفرة دائمًا بين علامات الاقتباس ` لتمكين التمييز. يمكن إدراج المعادلات بصيغة LaTeX بين علامتي اقتباس مزدوجتين ``. استخدم الأحرف Unicode بدلاً من تسلسل الهروب LaTeX الخاص بها، أي ``α = 1`` بدلاً من ``\\alpha = 1``.

2. Place the starting and ending """ characters on lines by themselves.

   هذا يعني، اكتب:

   ```julia """ ...

   ... """ f(x, y) = ... ```

   بدلاً من:

   ```julia """...

   ...""" f(x, y) = ... ```

   هذا يجعل من الواضح أين تبدأ وتنتهي تعليقات الوثائق.

3. احترم حد طول السطر المستخدم في الكود المحيط.

   يتم تحرير وثائق الدوال باستخدام نفس الأدوات المستخدمة في الشيفرة. لذلك، يجب أن تنطبق نفس القواعد. يُوصى بأن لا يتجاوز عرض الأسطر 92 حرفًا.

4. Provide information allowing custom types to implement the function in an # Implementation section. These implementation details are intended for developers rather than users, explaining e.g. which functions should be overridden and which functions automatically use appropriate fallbacks. Such details are best kept separate from the main description of the function's behavior.

5. للمستندات الطويلة، ضع في اعتبارك تقسيم الوثائق باستخدام عنوان # مساعدة موسعة. ستظهر وضعية المساعدة النموذجية فقط المواد الموجودة فوق العنوان؛ يمكنك الوصول إلى المساعدة الكاملة عن طريق إضافة '?' في بداية التعبير (أي، "??foo" بدلاً من "?foo").

Functions & Methods

يمكن أن تحتوي الدوال في جوليا على تنفيذات متعددة، تُعرف باسم الطرق. بينما من الجيد أن تحتوي الدوال العامة على غرض واحد، تسمح جوليا بتوثيق الطرق بشكل فردي إذا لزم الأمر. بشكل عام، يجب توثيق الطريقة الأكثر عمومية فقط، أو حتى الدالة نفسها (أي الكائن الذي تم إنشاؤه بدون أي طرق بواسطة function bar end). يجب توثيق الطرق المحددة فقط إذا كان سلوكها يختلف عن السلوكيات الأكثر عمومية. في أي حال، يجب ألا تكرر المعلومات المقدمة في أماكن أخرى. على سبيل المثال:

"""
    *(x, y, z...)

Multiplication operator. `x * y * z *...` calls this function with multiple
arguments, i.e. `*(x, y, z...)`.
"""
function *(x, y, z...)
    # ... [implementation sold separately] ...
end

"""
    *(x::AbstractString, y::AbstractString, z::AbstractString...)

When applied to strings, concatenates them.
"""
function *(x::AbstractString, y::AbstractString, z::AbstractString...)
    # ... [insert secret sauce here] ...
end

help?> *
search: * .*

  *(x, y, z...)

  Multiplication operator. x * y * z *... calls this function with multiple
  arguments, i.e. *(x,y,z...).

  *(x::AbstractString, y::AbstractString, z::AbstractString...)

  When applied to strings, concatenates them.

عند استرجاع الوثائق لوظيفة عامة، يتم دمج البيانات الوصفية لكل طريقة باستخدام دالة catdoc، والتي يمكن بالطبع تجاوزها لأنواع مخصصة.

Advanced Usage

تربط ماكرو @doc حجته الأولى بحجته الثانية في قاموس خاص بكل وحدة يسمى META.

لتسهيل كتابة الوثائق، يعامل المحلل اسم الماكرو @doc بشكل خاص: إذا كانت هناك استدعاء لـ @doc يحتوي على حجة واحدة، ولكن يظهر تعبير آخر بعد فاصل سطر واحد، فإن هذا التعبير الإضافي يُضاف كحجة إلى الماكرو. لذلك يتم تحليل الصيغة التالية كاستدعاء ذو حجتين لـ @doc:

@doc raw"""
...
"""
f(x) = x

هذا يجعل من الممكن استخدام تعبيرات أخرى غير السلاسل النصية العادية (مثل ماكرو السلسلة raw"") كوثيقة.

عند استخدامه لاسترجاع الوثائق، ستقوم ماكرو @doc (أو بنفس القدر، دالة doc) بالبحث في جميع قواميس META عن البيانات الوصفية ذات الصلة بالعنصر المعطى وإرجاعها. سيعرض الكائن المعاد (بعض محتوى Markdown، على سبيل المثال) نفسه بشكل ذكي بشكل افتراضي. يجعل هذا التصميم من السهل أيضًا استخدام نظام الوثائق بطريقة برمجية؛ على سبيل المثال، لإعادة استخدام الوثائق بين إصدارات مختلفة من دالة:

@doc "..." foo!
@doc (@doc foo!) foo

أو للاستخدام مع وظيفة الميتا برمجة في جوليا:

for (f, op) in ((:add, :+), (:subtract, :-), (:multiply, :*), (:divide, :/))
    @eval begin
        $f(a, b) = $op(a, b)
    end
end
@doc "`add(a, b)` adds `a` and `b` together" add
@doc "`subtract(a, b)` subtracts `b` from `a`" subtract

يجب إضافة الوثائق في الكتل غير العليا، مثل begin، if، for، let، والمُنشئات الداخلية، إلى نظام الوثائق عبر @doc أيضًا. على سبيل المثال:

if condition()
    @doc "..."
    f(x) = x
end

سأضيف الوثائق إلى f(x) عندما تكون condition() true. لاحظ أنه حتى إذا خرجت f(x) عن النطاق في نهاية كتلة، ستبقى وثائقها.

من الممكن استخدام البرمجة الميتا للمساعدة في إنشاء الوثائق. عند استخدام إدراج السلاسل النصية داخل سلسلة الوثائق، ستحتاج إلى استخدام $ إضافي كما هو موضح بـ $($name):

for func in (:day, :dayofmonth)
    name = string(func)
    @eval begin
        @doc """
            $($name)(dt::TimeType) -> Int64

        The day of month of a `Date` or `DateTime` as an `Int64`.
        """ $func(dt::Dates.TimeType)
    end
end

Dynamic documentation

أحيانًا تعتمد الوثائق المناسبة لنسخة من نوع ما على قيم الحقول لتلك النسخة، بدلاً من الاعتماد فقط على النوع نفسه. في هذه الحالات، يمكنك إضافة طريقة إلى Docs.getdoc لنوعك المخصص التي تعيد الوثائق على أساس كل نسخة. على سبيل المثال،

struct MyType
    value::Int
end

Docs.getdoc(t::MyType) = "Documentation for MyType with value $(t.value)"

x = MyType(1)
y = MyType(2)

?x سيعرض "التوثيق لـ MyType بالقيمة 1" بينما ?y سيعرض "التوثيق لـ MyType بالقيمة 2".

Syntax Guide

هذا الدليل يوفر نظرة شاملة حول كيفية إرفاق الوثائق بجميع تراكيب بناء الجملة في جوليا التي يمكن توفير الوثائق لها.

في الأمثلة التالية، يتم استخدام "..." لتوضيح سلسلة توثيق عشوائية.

$ and \ characters

لا تزال أحرف $ و \ تُفسر كاستبدال السلاسل أو بداية تسلسل الهروب في وثائق السلاسل أيضًا. يمكن استخدام ماكرو السلسلة raw"" مع ماكرو @doc لتجنب الحاجة إلى الهروب منها. هذا مفيد عندما تتضمن وثائق السلاسل أمثلة على كود المصدر LaTeX أو Julia تحتوي على استبدال:

@doc raw"""
```math
\LaTeX
```
"""
function f end

Functions and Methods

"..."
function f end

"..."
f

يضيف سلسلة توثيق "..." إلى الدالة f. النسخة الأولى هي الصيغة المفضلة، ومع ذلك كلاهما متكافئ.

"..."
f(x) = x

"..."
function f(x)
    return x
end

"..."
f(x)

يضيف سلسلة الوثائق "..." إلى الطريقة f(::Any).

"..."
f(x, y = 1) = x + y

يضيف سلسلة توثيق "..." إلى طريقتين، وهما f(::Any) و f(::Any, ::Any).

Macros

"..."
macro m(x) end

يضيف سلسلة توثيق "..." إلى تعريف الماكرو @m(::Any).

"..."
:(@m1)

"..."
macro m2 end

يضيف سلسلة الوثائق "..." إلى الماكروهات المسماة @m1 و @m2.

Types

"..."
abstract type T1 end

"..."
mutable struct T2
    ...
end

"..."
struct T3
    ...
end

يضيف التعليق التوضيحي "..." إلى الأنواع T1 و T2 و T3.

"..."
T1

"..."
T2

"..."
T3

يضيف التعليق التوضيحي "..." إلى الأنواع T1 و T2 و T3. النسخة السابقة هي الصيغة المفضلة، ومع ذلك فإن كلاهما متساويان.

"..."
struct T
    "x"
    x
    "y"
    y

    @doc "Inner constructor"
    function T()
        new(...)
    end
end

يضيف سلسلة الوثائق "..." إلى النوع T، و"x" إلى الحقل T.x، و"y" إلى الحقل T.y، و"الباني الداخلي" إلى الباني الداخلي T(). ينطبق أيضًا على أنواع mutable struct.

Modules

"..."
module M end

module M

"..."
M

end

يضيف سلسلة الوثائق "..." إلى Module M. إضافة سلسلة الوثائق فوق Module هي الصيغة المفضلة، ومع ذلك، كلاهما متكافئ.

"..."
baremodule M
# ...
end

baremodule M

import Base: @doc

"..."
f(x) = x

end

توثيق baremodule عن طريق وضع سلسلة توضيحية فوق التعبير يستورد تلقائيًا @doc إلى الوحدة. يجب إجراء هذه الاستيرادات يدويًا عندما لا يتم توثيق تعبير الوحدة.

Global Variables

"..."
const a = 1

"..."
b = 2

"..."
global c = 3

يضيف سلسلة الوثائق "..." إلى Bindings a و b و c.

تُستخدم Bindings لتخزين مرجع إلى Symbol معين في Module دون تخزين القيمة المرجعية نفسها.

"..."
f(x) = x + 1
const alias = f

f(x) = x + 1
"..."
const alias = f

"..."
sym

يضيف سلسلة الوثائق "..." إلى القيمة المرتبطة بـ sym. ومع ذلك، يُفضل توثيق sym حيث يتم تعريفه.

Multiple Objects

"..."
a, b

يضيف سلسلة الوثائق "..." إلى a و b، كل منهما يجب أن يكون تعبيرًا يمكن توثيقه. هذه الصيغة تعادل

"..."
a

"..."
b

يمكن توثيق أي عدد من التعبيرات معًا بهذه الطريقة. يمكن أن تكون هذه الصيغة مفيدة عندما تكون دالتان مرتبطتان، مثل النسخ غير المتغيرة والمتغيرة f و f!.

Macro-generated code

"..."
@m expression

يضيف سلسلة الوثائق "..." إلى التعبير الناتج عن توسيع @m expression. وهذا يسمح بتوثيق التعبيرات المزينة بـ @inline، @noinline، @generated، أو أي ماكرو آخر بنفس الطريقة التي يتم بها توثيق التعبيرات غير المزينة.

يجب على مؤلفي الماكرو أن يأخذوا في الاعتبار أن الماكرو التي تولد تعبيرًا واحدًا فقط ستدعم تلقائيًا نصوص الوثائق. إذا كان الماكرو يعيد كتلة تحتوي على تعبيرات فرعية متعددة، فيجب تمييز التعبير الفرعي الذي يجب توثيقه باستخدام الماكرو @__doc__.

تستخدم الماكرو @enum @__doc__ للسماح بتوثيق Enums. يجب أن يكون فحص تعريفه مثالًا على كيفية استخدام @__doc__ بشكل صحيح.

@__doc__(ex)

macro example(f)
    quote
        $(f)() = 0
        @__doc__ $(f)(x) = 1
        $(f)(x, y) = 2
    end |> esc
end