Rust: تطوير دليل أسلوب doc-comment

: +1: لمناقشة هذا. أرغب في المساهمة بالمستندات ، لكني لا أرغب في بذل المزيد من العمل من أجلك بعد الانتهاء من ذلك. ؛)

للمقارنة ، فإن أسلوب Python القياسي هو استخدام الأمر "Return the…" ، والذي أجده يعمل بشكل جيد:

http://www.python.org/dev/peps/pep-0257/#one -line-docstrings

استقر جو على الأسلوب غير الضروري: http://golang.org/pkg/

زيارة للفرز.

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

/**
 * doc string
 */

أنا أيضا أفضل الحتمية. يحتاج النمط أيضًا إلى تضمين بناء جملة موحد للإشارة إلى الأنواع والوسيطات ، لذلك يمكن أن يقوم rustdoc بالتعليق عليها أو إنشاء ارتباط تشعبي لها بشكل صحيح. هذا على الرغم من الطريق

زيارة للفرز. لدي رأي قليل جدا حول هذا.

النمط الوصفي:

• C # : Sorts the elements ... http://msdn.microsoft.com/en-gb/library/w56d4y5z٪28v=vs.85٪29.aspx#United٪ 20Kingdom٪ 20٪ 28English٪ 29
• C ++ : ... sorts the elements ... http://www.sgi.com/tech/stl/sort.html
• اذهب : ... sorts data ... http://golang.org/pkg/sort/#Sort
• Haskel l: ... takes an element and a list and inserts the element into the list ... http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-List.html
• جافا : Sorts the specified array ... http://docs.oracle.com/javase/7/docs/api/java/util/Arrays.html
• روبي : Sorts self in place. http://www.ruby-doc.org/core-2.1.0/Array.html#method -i-sort-21

أسلوب الأمر:

• أوكام l: ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
• بايثون : Sort the items ... http://docs.python.org/2/tutorial/datastructures.html

أفضل النسخ الوصفية بنفسي لأن تعريف الطريقة لا يفعل أي شيء حتى أخبره:

class Machine
{
    // Self-destructs the machine, if necessary.
    void self_destruct();
};

// Self-destruct!
if ( emergency )
  machine.self_destruct();

أنا عاقل لحجة kud1ing. علاوة على ذلك ، إذا قرأت سطرًا بصوت عالٍ بالطريقة التي تم تقديمها في المستند:

صفر تُرجع الهوية المضافة ، 0.

ثم الشكل التقريري يجعلها جملة حقيقية "zero" returns the additive identity, 0. .

Armavica : وهو في الواقع شكل قصير من The method "zero" returns the additive identity, 0 .

التوثيق والواجهة هو تقديم شيء للجمهور. أعتقد أن صيغة الأمر منطقية أكثر ، عندما تشرح ماذا / كيف / لماذا يحدث شيء ما في التنفيذ.

يوجد أيضًا https://github.com/mozilla/rust/issues/9403 حول أسلوب الأمثلة في التوثيق.

محراث.

نسخة إلى https://github.com/mozilla/rust/issues/12928

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

أعتقد أن تسمية هذا بأسلوب الأمر أمر خاطئ. إنه ليس أمرًا ضروريًا ، لأنه لا يأمر أي شخص بفعل أي شيء. أعتقد أن هذا هو أول شخص الحاضر الدلالي. أظن أن الرغبة في الكتابة

/// Frob the twaddle.
fn frob() {}

تنبع من عقلية "أنا الوظيفة. ماذا أفعل؟"

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

الحجة المعقولة الوحيدة التي يمكنني رؤيتها لاعتبار هذا الأمر أمرًا حتميًا وليس المؤشر الحالي للشخص الأول هو عندما يصف docstring إعلانًا عن الوظيفة يتوقع من المستخدم تنفيذه. هذا شائع جدًا في لغات OO ، ولكن في Rust ينطبق فقط على طرق السمات. تقترح هذه الحالة استخدام الأمر لأنه يخبرك بما يجب عليك فعله من أجل تنفيذ الطريقة بشكل صحيح.

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

شيء آخر يجب التعامل معه: واصلات أو شرطات قصيرة:

https://en.wikipedia.org/wiki/Dash#Relationships_and_connections

التفضيل للشرطة الإنجليزية بدلاً من الواصلة في أنواع المصطلحات الخاصة بالإحداثيات / العلاقة / الاتصال هو مسألة تفضيل النمط ، وليس "صحة" إملائية متأصلة ؛ كلاهما "صحيح" بالتساوي ، وكل منهما هو النمط المفضل في بعض أدلة الأنماط.

لقد قدمت RFC: https://github.com/rust-lang/rfcs/pull/505