การจัดทำเอกสารด้วยคอมเมนต์ dartdoc

แพ็กเกจที่ยอดเยี่ยมย่อมมาพร้อมเอกสารที่ยอดเยี่ยม Dart เปลี่ยนความคิดเห็นรูปแบบพิเศษให้เป็นข้อมูลอ้างอิงที่เรียกดูได้ ดังนั้น เอกสารประกอบ จึงเป็นฟีเจอร์สำคัญ ไม่ใช่สิ่งที่ค่อยทำทีหลัง 📝

ความคิดเห็นเอกสารเริ่มต้นด้วยเครื่องหมายทับสามตัว ความคิดเห็นเอกสาร เหล่านี้จะอยู่เหนือการประกาศโดยตรงและอธิบายว่าการประกาศนั้นทำอะไรให้ผู้ใช้

เริ่มความคิดเห็นเอกสารทุกส่วนด้วยประโยค สรุป สั้น ๆ หนึ่งประโยค เครื่องมือจะแสดงบรรทัดแรกนี้ในรายการต่าง ๆ ดังนั้นควรเขียนให้ชัดเจนและสมบูรณ์ในตัวเอง

ความคิดเห็นเอกสารรองรับ Markdown คุณจึงเพิ่มการเน้นข้อความ รายการ และลิงก์ได้ หน้าเว็บที่แสดงผลบน pub.dev จะดูเรียบร้อยโดยแทบไม่ต้องออกแรง

ครอบชื่อด้วยวงเล็บเหลี่ยมเพื่อสร้าง ลิงก์เชื่อมโยง ที่ใช้งานได้ ผู้อ่านจะกระโดดไปยังคลาสหรือเมธอดที่เกี่ยวข้องในเอกสารที่สร้างขึ้นได้โดยตรง

แสดงการใช้งานจริงภายในบล็อกโค้ดแบบมีรั้วในความคิดเห็น ตัวอย่าง การใช้งาน สั้น ๆ สอนให้เข้าใจได้เร็วกว่าย่อหน้าหลายย่อหน้า และช่วยให้ผู้ใช้มั่นใจว่าโค้ดใช้งานได้

พยายามจัดทำเอกสารให้คลาส ฟังก์ชัน และฟิลด์ สาธารณะ ทุกตัว สมาชิกส่วนตัวที่ขึ้นต้นด้วยขีดล่างอาจไม่ต้องมีคำอธิบาย แต่ทุกสิ่งที่ส่งออกควรมีคำอธิบายอย่างน้อยหนึ่งประโยค

วางความคิดเห็นเอกสารไว้เหนือคำสั่งไลบรารีเพื่ออธิบายทั้งไฟล์ ความคิดเห็นระดับไลบรารี นี้จะกลายเป็นข้อความต้อนรับสำหรับส่วนนั้นของ API

เรียกใช้เครื่องมือ dartdoc เพื่อเปลี่ยนความคิดเห็นของคุณให้เป็นเว็บไซต์แบบคงที่ pub.dev จะเรียกใช้เครื่องมือนี้ให้โดยอัตโนมัติเมื่อคุณเผยแพร่

pub.dev ให้รางวัลแพ็กเกจที่มีเอกสารครบถ้วน ความครอบคลุมของเอกสารที่สูงขึ้นช่วยเพิ่มคะแนนและส่งสัญญาณถึงคุณภาพแก่ผู้ที่กำลังเลือกการพึ่งพา ⭐

เนื่องจากความคิดเห็นเอกสารอยู่ข้างโค้ด จึงอัปเดตไปพร้อมกันได้ง่าย มองว่า เอกสาร ที่ล้าสมัยเป็นเหมือนข้อผิดพลาด และแก้ไขเมื่อพฤติกรรมของโค้ดเปลี่ยนไป

ความคิดเห็นรูปแบบใดที่ Dart ถือว่าเป็นความคิดเห็นเอกสาร

ตอนนี้คุณสามารถเขียน ความคิดเห็นเอกสารแบบสามขีด ลิงก์สัญลักษณ์ เพิ่มตัวอย่าง และสร้างเว็บไซต์ด้วย dartdoc ได้แล้ว เอกสารที่ชัดเจนช่วยดึงดูดผู้ใช้ 🙌