Apakah sintaks untuk komentar TypeScript didokumentasikan di mana saja?

Dan kebetulan, apakah sekarang mendukung sistem C # ///?

Sintaks yang tepat sekarang digunakan oleh TSDoc . Ini akan memungkinkan Anda untuk membuat komentar Anda dipahami oleh Visual Studio Code atau alat dokumentasi lainnya.

Ikhtisar sintaks yang baik tersedia di sini dan terutama di sini . Spesifikasi yang tepat harus "segera" ditulis .

File lain yang patut diperiksa adalah file ini di mana Anda akan melihat tag standar yang bermanfaat.

Catatan : Anda tidak boleh menggunakan JSDoc, seperti yang dijelaskan di halaman utama TSDoc: Mengapa JSDoc tidak bisa menjadi standar? Sayangnya, tata bahasa JSDoc tidak ditentukan secara ketat tetapi disimpulkan dari perilaku implementasi tertentu. Mayoritas tag JSDoc standar sibuk dengan memberikan anotasi tipe untuk JavaScript biasa, yang merupakan masalah yang tidak relevan untuk bahasa yang sangat diketik seperti TypeScript. TSDoc mengatasi keterbatasan ini sambil juga menangani serangkaian tujuan yang lebih canggih.

Masa depan

Tim TypeScript, dan tim TypeScript lain yang terlibat, berencana untuk membuat spesifikasi TSDoc formal standar. The 1.0.0Draft belum selesai belum: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

Arus

TypeScript menggunakan JSDoc. misalnya

/** This is a description of the foo function. */
function foo() {
}

Untuk mempelajari jsdoc: https://jsdoc.app/

Tetapi Anda tidak perlu menggunakan ekstensi anotasi jenis di JSDoc.

Anda dapat (dan harus) masih menggunakan tag blok jsdoc lainnya seperti @returnsdll.

Contoh

Contoh saja. Fokus pada jenis (bukan konten).

Versi JSDoc (jenis pemberitahuan dalam dokumen):

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

Versi TypeScript (perhatikan lokasi ulang jenis):

/**
 * Takes two numbers and returns their sum
 * @param a first input to sum
 * @param b second input to sum
 * @returns sum of a and b
 */
function sum(a: number, b: number): number {
    return a + b;
}

Anda dapat menambahkan informasi tentang parameter, pengembalian, dll. Juga menggunakan:

/**
* This is the foo function
* @param bar This is the bar parameter
* @returns returns a string version of bar
*/
function foo(bar: number): string {
    return bar.toString()
}

Ini akan menyebabkan editor seperti VS Code untuk menampilkannya sebagai berikut:

Anda dapat menggunakan komentar seperti pada JavaScript biasa:

Sintaks TypeScript adalah superset dari sintaks Ecmascript 5 (ES5). [...]

Dokumen ini menjelaskan tata bahasa sintaksis yang ditambahkan oleh TypeScript

Selain itu, saya hanya menemukan ini tentang komentar dalam spesifikasi bahasa:

TypeScript juga menyediakan bagi pemrogram JavaScript sistem anotasi jenis opsional . Anotasi jenis ini seperti komentar JSDoc yang ditemukan dalam sistem Penutupan, tetapi dalam TypeScript mereka diintegrasikan langsung ke dalam sintaks bahasa. Integrasi ini membuat kode lebih mudah dibaca dan mengurangi biaya pemeliharaan untuk menyinkronkan anotasi jenis dengan variabel terkait.

11.1.1 Ketergantungan File Sumber:

Komentar formulir /// <reference path="..."/>menambahkan ketergantungan pada file sumber yang ditentukan dalam argumen path. Jalur diselesaikan relatif ke direktori file sumber yang mengandung

Sumber:
https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

Karenanya, TypeScript adalah superset sintaksis JavaScript yang ketat

• Komentar satu baris dimulai dengan //
• Komentar multi-baris dimulai dengan / * dan diakhiri dengan * /