วิธีเก็บตัวอย่างโค้ดใน javadocs เป็นปัจจุบัน


9

ฉันกำลังทำงานในห้องสมุดขนาดเล็กที่ให้การใช้งานของตัวชี้วัดสตริงพื้นฐานที่รู้จักกันดี ส่วนใหญ่เพื่อการศึกษาของฉันเอง ดังนั้นการพัฒนาจึงเกิดขึ้นทุกครั้งที่ฉันมีเวลาว่าง

ด้วยเหตุนี้ฉันจึงเป็นกระบวนการอัตโนมัติโดยอัตโนมัติดังนั้นฉันจึงสามารถเผยแพร่เวอร์ชันได้บ่อยเท่าที่ฉันทำงานโดยไม่ต้องใช้ความพยายามมากเกินไป อย่างไรก็ตามการบำรุงรักษาเอกสาร Java ยังคงเป็นภาระเพราะมันมีตัวอย่าง

เนื่องจาก API วิวัฒนาการขึ้นฉันต้องตรวจสอบตัวอย่างแต่ละครั้งซ้ำแล้วซ้ำอีก มีวิธีที่ดีกว่าในการทำเช่นนี้?

ฉันได้พิจารณาการย้ายเอกสารและตัวอย่างไปเป็นโครงการแยกต่างหาก (เช่นCaliper Tutorial ) เพื่อให้สามารถนำแฟคตอริ่งและคอมไพล์ไปพร้อมกับรหัสปกติอีกครั้ง อย่างไรก็ตามมันจะย้ายเอกสารออกไปจากชั้นเรียนที่มันเป็นเรื่องเกี่ยวกับ

ใช่แล้ว ฉันต้องการเค้กและกินด้วย : D

 * <h2>Tokenization</h2>
 * 
 * Tokenization cuts up a string into tokens e.g.
 * <code>chilperic ii son of childeric ii</code> is tokenized into
 * <code>[chilperic, ii, son, of,
 * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing
 * the individual tokens e.g.
 * <code>[ch,hi,il,il,lp,pe,er,ri,ic, ii, so,on, of, ch,hi,il,ld,de,er,ri,ic, ii]</code>
 * <p>
 * 
 * <pre>
 * <code>
 * {@code
 *  return new StringMetricBuilder()
 *          .with(new SimonWhite<String>())
 *          .tokenize(new Whitespace())
 *          .tokenize(new QGram(2))
 *          .build();
 * }
 * </code>
 * </pre>
 * 
 * <p>

ถ้าข้างต้นมันเป็นนามธรรมเกินไป นี่คือตัวอย่างของเอกสาร ขณะนี้ฉันกำลังเพิ่มตัวสร้างแบบคงที่ตามคำแนะนำโดยจาวาที่มีประสิทธิภาพเช่นTokenizers.createQGram(2)ในขณะที่คิดค่าเสื่อมราคาวิธีการตัวสร้าง ทุกครั้งที่ฉันทำสิ่งนี้ฉันต้องอัปเดตโค้ดตัวอย่างด้านบนและตรวจสอบว่ายังใช้งานได้หรือไม่

คำตอบ:


8

สิ่งนี้อาจไม่ตอบคำถามของคุณ - ขึ้นอยู่กับความต้องการ 'จำนวน' ที่จะมีตัวอย่างเหล่านี้ในเอกสาร

บางทีคุณสามารถทำมุมที่แตกต่าง: ให้ตัวอย่างในการทดสอบ JUnit ของคุณ (อาจเป็นแพคเกจเช่น com.examples) ปัญหาเกี่ยวกับโค้ดในคอมเม้นต์ก็คือ IDE ของคุณจะไม่สนใจมันส่วนใหญ่ แต่ IDE ของคุณจะตรวจสอบรหัสในการทดสอบ JUnit ของคุณ ด้วยการทำเช่นนี้คุณจะมั่นใจได้ว่าตัวอย่างรหัสนั้น 'ถูกต้อง' - การทดสอบจะไม่รวบรวมหรือล้มเหลวหากคุณยังไม่ได้อัปเดต

ฉันไม่ใช่ตัวช่วยสร้างด้วย Javadocs แต่อาจมีวิธีการเชื่อมโยงเอกสารประกอบของไฟล์ต้นฉบับของคุณกับไฟล์ JUnit ด้วยรหัสตัวอย่างในนั้น ฉันไม่รู้จริงๆว่าจะเริ่มจากตรงไหน googling คร่าวๆแสดงให้ฉันเห็นแท็ก@see ฉันทดสอบในโครงการ แต่ยังไม่ได้ทดสอบใน javadoc จริงหลังจากที่ถูกสร้างขึ้น

สิ่งนี้จะต้องมีการค้นคว้าล่วงหน้า แต่ฉันคิดว่าคุณน่าจะดีขึ้นในระยะยาวหากตัวอย่างโค้ดของคุณกำลังรวบรวม

คุณสามารถเพิ่มความครอบคลุมของรหัสเมื่อเรียกใช้ตัวอย่าง JUnit ของคุณ วิธีนี้คุณจะรู้ได้ทันทีว่าตัวอย่างโค้ดของคุณครอบคลุมเท่าไร


ความสามารถในการทดสอบหน่วยทำให้ฉันมั่นใจ ฉันจะแยกเอกสารเป็นคำอธิบายฟังก์ชั่นธรรมดาและย้ายตัวอย่างไปยังโครงการกวดวิชา การลิงก์ไปยังไฟล์บน GitHub อาจจะค่อนข้างอึดอัด แต่ก็เป็นการแลกเปลี่ยนที่ยอมรับได้
MP Korstanje
โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.