Rust: Kembangkan panduan gaya komentar dokumen

:+1: untuk membahas ini. Saya ingin menyumbangkan dokumen, tetapi saya tidak ingin membuat lebih banyak pekerjaan untuk Anda setelah selesai. ;)

Sebagai perbandingan, gaya Python standar adalah menggunakan perintah "Kembalikan ...", yang menurut saya berfungsi dengan baik:

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

Go telah memilih gaya non-imperatif: http://golang.org/pkg/

Mengunjungi untuk triase.

Secara pribadi, saya lebih suka kata kerja imperatif, dan titik di akhir. Adapun gaya komentar dokumen, saya tidak berpikir kita harus memaksakan cara tertentu di atas yang lain, setidaknya tidak sementara bahasa mendefinisikan banyak cara untuk melakukannya. Juga, cara pilihan saya adalah

/**
 * doc string
 */

Saya juga lebih suka yang imperatif. Gaya juga perlu menyertakan sintaks terpadu untuk merujuk ke tipe dan argumen, jadi rustdoc dapat membuat anotasi/hyperlink dengan benar. Itu di ujung jalan sekalipun

Mengunjungi untuk triase. Saya memiliki sedikit pendapat tentang ini.

Gaya deskriptif:

• 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
• Buka : ... 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
• Java : Sorts the specified array ... http://docs.Oracle.com/javase/7/docs/api/java/util/Arrays.html
• Ruby : Sorts self in place. http://www.ruby-doc.org/core-2.1.0/Array.html#method -i-sort-21

Gaya imperatif:

• Ocam l: ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
• Python : Sort the items ... http://docs.python.org/2/tutorial/datastructures.html

Saya sendiri lebih suka versi deskriptif karena definisi metode tidak melakukan apa pun sampai saya menyuruhnya:

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

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

Saya masuk akal untuk argumen kud1ing. Selanjutnya, jika Anda membacakan sebuah baris dengan cara yang disajikan dalam dokumen:

zero Mengembalikan identitas aditif, 0.

kemudian bentuk deklaratif membuatnya menjadi kalimat nyata "zero" returns the additive identity, 0. .

@Armavica : Yang sebenarnya adalah bentuk pendek dari The method "zero" returns the additive identity, 0 .

Mendokumentasikan dan antarmuka adalah menyajikan sesuatu kepada penonton. Saya pikir bentuk imperatif lebih masuk akal, ketika Anda menjelaskan apa/bagaimana/mengapa sesuatu terjadi dalam implementasi.

Ada juga https://github.com/mozilla/rust/issues/9403 tentang gaya contoh dalam dokumentasi.

Bajak.

cc https://github.com/mozilla/rust/issues/12928

Dari komentar di sini, gaya deskriptif (misalnya, "Mengubah byte menjadi string.") tampaknya lebih populer daripada gaya imperatif ("Mengubah byte menjadi string."). Saya tidak terlalu peduli ke mana kita pergi, tetapi akan menyenangkan untuk memiliki keputusan resmi tentang ini.

Saya pikir menyebut ini gaya imperatif salah. Itu tidak penting, karena itu tidak memerintahkan siapa pun untuk melakukan apa pun. Saya pikir itu adalah orang pertama yang hadir indikatif. Saya menduga bahwa dorongan untuk menulis

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

berasal dari pola pikir "Saya adalah fungsi. Apa yang saya lakukan?", jadi itu adalah indikatif orang pertama saat ini.

Namun, saat membaca dokumentasi, sebagian besar pembaca secara alami akan memperlakukan fungsi tersebut sebagai subjek tunggal orang ketiga alih-alih subjek orang pertama. Untuk itu, dokumentasi harus ditulis dalam orang ketiga tunggal, bukan orang pertama.

Satu-satunya argumen yang masuk akal yang dapat saya lihat untuk mempertimbangkan ini sebagai imperatif daripada indikatif orang pertama saat ini adalah ketika docstring menjelaskan deklarasi fungsi yang diharapkan dapat diterapkan oleh pengguna. Ini sangat umum dalam bahasa OO, tetapi di Rust itu hanya berlaku untuk metode sifat. Kasus ini menyarankan penggunaan imperatif karena memberi tahu Anda apa yang harus Anda lakukan untuk menerapkan metode dengan benar.

Tapi saya tidak menganggap argumen ini persuasif. Kasus penggunaan utama untuk dokumentasi memberi tahu pembaca cara _menggunakan_ API, bukan cara mengimplementasikannya. Jumlah penggunaan API jauh melebihi jumlah implementasi (dalam semua kasus kecuali yang paling esoterik). Oleh karena itu, saya percaya bahwa lebih masuk akal untuk menggunakan indikatif saat ini dalam bentuk orang ketiga tunggal daripada menggunakan imperatif, bahkan untuk metode sifat.

Hal lain yang harus dihadapi: tanda hubung atau tanda hubung:

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

Preferensi untuk tanda hubung en daripada tanda hubung dalam jenis istilah koordinat/hubungan/hubungan ini adalah masalah preferensi gaya, bukan "kebenaran" ortografis yang melekat; keduanya sama-sama "benar", dan masing-masing adalah gaya yang disukai di beberapa panduan gaya.

Saya telah mengirimkan RFC: https://github.com/rust-lang/rfcs/pull/505