การแปล: การใช้ไวยากรณ์ Markdown ในความคิดเห็น Javadoc

การใช้ไวยากรณ์ Markdown ในความคิดเห็น Javadoc

ในโพสต์นี้ เราจะมาดูกันว่าคุณสามารถเขียนความคิดเห็น Javadoc โดยใช้ Markdownแทนการใช้ไวยากรณ์ Javadoc มาตรฐาน ได้อย่างไร แล้วมาร์กดาวน์คืออะไร? Markdown เป็นภาษามาร์กอัปธรรมดาที่สามารถเลือกแปลเป็น HTML โดยใช้เครื่องมือชื่อเดียวกันได้ Markdown ถูกนำมาใช้กันอย่างแพร่หลายในการจัดรูปแบบไฟล์ Readme เมื่อเขียนโพสต์ในฟอรัม และในโปรแกรมแก้ไขข้อความเพื่อสร้างเอกสารข้อความที่สวยงามได้อย่างรวดเร็ว (Wikipedia: Markdown ) ข้อความที่จัดรูปแบบใน Markdown นั้นอ่านง่ายมาก Markdown มีหลายรสชาติที่ใช้บน Stack Overflow หรือ GitHub เพื่อจัดรูปแบบเนื้อหาที่ผู้ใช้สร้างขึ้น

การติดตั้ง

โดยดีฟอลต์ เครื่องมือ Javadoc ใช้ข้อคิดเห็น Javadoc เพื่อสร้างเอกสารคู่มือ API เป็น HTML กระบวนการ นี้สามารถกำหนดค่าใหม่ได้โดยใช้Doclets Doclets คือโปรแกรม Java ที่ระบุเนื้อหาและการจัดรูปแบบของไฟล์เอาต์พุตของเครื่องมือ Javadoc Markdown-doclet แทนที่ Java Doclet มาตรฐานและทำให้นักพัฒนาสามารถใช้ไวยากรณ์ Markdown ในความคิดเห็น Javadoc ของตนได้ คุณสามารถติดตั้งใน Maven โดยใช้maven-javadoc-plugin maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

การเขียนความคิดเห็นใน Markdown

ตอนนี้คุณสามารถใช้ไวยากรณ์ Markdown เพื่อเขียนความคิดเห็น Javadoc: /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } หลังจากดำเนินการ

mvn javadoc:Javadoc

เอกสาร HTML API ที่สร้างขึ้นตั้งอยู่ที่

เป้าหมาย/ไซต์/apidocs.

เอกสารที่สร้างขึ้นสำหรับโค้ดด้านบนมีลักษณะดังนี้: ดังที่คุณเห็นจากรูปภาพ ความคิดเห็นของ Javadoc จะถูกแปลงเป็น HTML อย่างสมบูรณ์แบบ

บทสรุป

Markdown มีข้อได้เปรียบเหนือไวยากรณ์ Javadoc มาตรฐานอย่างชัดเจน: อ่านซอร์สโค้ดได้ง่ายกว่ามาก ลองดูความคิดเห็นของเมธอดบางส่วนใน java.util.Map: หลายเมธอดเต็มไปด้วยแท็กการจัดรูปแบบและอ่านได้ยากโดยไม่ต้องใช้เครื่องมือเพิ่มเติม แต่คุณต้องจำไว้ว่า Markdown อาจทำให้เกิดปัญหากับเครื่องมือและ IDE ที่สามารถทำงานกับไวยากรณ์ Javadoc มาตรฐานเท่านั้น ที่มา: การใช้ไวยากรณ์ Markdown ในความคิดเห็น JavadocจากMichael Scharhag พันธมิตร JCG ของเราจาก บล็อก mscharhag, Programming and Stuff