คำอธิบายประกอบ
1. คำอธิบายประกอบคืออะไร? (คำอธิบายประกอบหรือความคิดเห็น)
คำอธิบายประกอบการแปลที่ถูกต้องควรเป็น - คำอธิบายประกอบ มันแตกต่างอย่างสิ้นเชิงจากความคิดเห็น
คำอธิบายประกอบเป็นคุณสมบัติที่แนะนำโดย JDK5.0 และรุ่นใหม่กว่า มันอยู่ในระดับเดียวกับคลาสอินเทอร์เฟซและการแจกแจงและสามารถกลายเป็นประเภทของ Java
ไวยากรณ์เริ่มต้นด้วย @
ความคิดเห็นเป็นคำอธิบายการท่องจำหรือคำอธิบายที่ทำโดยโปรแกรมเมอร์ของคลาสซอร์สโค้ด, วิธีการคุณสมบัติ ฯลฯ (เช่นวิธีการนี้ใช้สำหรับ) และสำหรับคนที่จะเห็น
คำอธิบายประกอบเป็นส่วนที่คอมไพเลอร์ Java สามารถเข้าใจได้และมีไว้เพื่อให้คอมไพเลอร์ดู
มายกตัวอย่างง่ายๆเพื่อดูการใช้งานและฟังก์ชั่นของคำอธิบายประกอบ
@Override เป็นคำอธิบายประกอบ Java ในตัวทั่วไป ฟังก์ชั่นของมันคือการตรวจสอบว่าวิธีการที่กำหนดไว้ในคลาสย่อยนั้นถูกต้องเมื่อรวบรวมรหัสหรือไม่
คำอธิบายประกอบแพ็คเกจ; สัตว์นามธรรมระดับสาธารณะ {โมฆะนามธรรมสาธารณะ Eat (); } คำอธิบายประกอบแพ็คเกจ; แมวชั้นเรียนสาธารณะขยายสัตว์ {@Override โมฆะสาธารณะกิน (อาหารสตริง) {}} ที่นี่ในแมว subclass วิธีการ EAT นั้นมีคำอธิบายประกอบเป็นวิธีที่เขียนทับคลาสแม่ แต่มีพารามิเตอร์มากกว่าหนึ่งพารามิเตอร์มากกว่าวิธีการคลาสแม่
หากคุณกำลังแก้ไขใน Eclipse จะมีพรอมต์สภากาชาด (การรวบรวมรหัสจะไม่ถูกส่งผ่าน)
หากคุณลบคำอธิบายประกอบ @Override ไม่มีปัญหาในการรวบรวม แต่วิธี EAT ใน CAT เป็นวิธีการใหม่ของคลาสนี้ไม่ได้สืบทอดมาจากคลาสหลัก
2. คำอธิบายประกอบในตัว Java ทั่วไป
รวมถึง @Override คำอธิบายประกอบ Java ในตัวอื่น ๆ คืออะไร?
1. @deprecated
ไม่แนะนำให้ใช้คำอธิบายประกอบและสามารถใช้กับวิธีการและชั้นเรียน
โดยพื้นฐานแล้ววิธีการและชั้นเรียนนี้จะถูกทอดทิ้งและไม่แนะนำด้วยเหตุผลบางอย่างเช่นการอัพเกรดหรือประสิทธิภาพ แต่ต้องเก็บไว้เพื่อความเข้ากันได้หรือเหตุผลอื่น ๆ
ดังนั้นใส่คำอธิบายประกอบนี้ไว้
มีตัวอย่างมากมายใน Java เอง API หากคุณใส่คำอธิบายประกอบนี้ในวิธีการนี้คุณจะเห็นวิธีการทางเลือกใหม่ใด
เมื่อเขียนโค้ดใน Eclipse วิธีที่เพิ่มคำอธิบายประกอบนี้จะเพิ่ม Strikethroughs ให้กับทั้งการประกาศและการโทร
2.@แทนที่
3.@uspresswarnings
ไม่สนใจคำเตือน
หากรหัสของคุณมีคำเตือนบางอย่างเกี่ยวกับการเปลี่ยนแปลงหรือส่วนอื่น ๆ แต่คุณต้องการเพิกเฉยต่อคำเตือนเหล่านี้คุณสามารถใช้คำอธิบายประกอบนี้ได้
1) คำเตือนเมื่อการคัดค้านใช้คลาสหรือวิธีการที่ไม่ได้รับการสนับสนุน
2) คำเตือนที่ไม่ถูกตรวจสอบเมื่อทำการแปลงที่ไม่ได้ตรวจสอบ
3) คำเตือน Fallthrough จะปรากฏขึ้นเมื่อไม่เพิ่มการดำเนินการพักหลังจากใช้เคสทำให้โปรแกรมดำเนินการต่อเพื่อดำเนินการตามคำสั่งกรณีอื่น ๆ
4) การเตือนเส้นทางเมื่อตั้งค่าคลาส classpath หรือเส้นทางไฟล์ต้นฉบับที่ไม่ถูกต้อง
5) คำเตือนแบบอนุกรมเมื่อคำจำกัดความของ SerialVersionuid หายไปในระดับ serializable
6) คำเตือนอย่างเป็นกลางหากประโยคใด ๆ ในที่สุดไม่สามารถทำให้เสร็จได้ตามปกติ
7) คำเตือนทั้งหมดเกี่ยวกับสถานการณ์ทั้งหมดข้างต้น
3. คำอธิบายประกอบที่กำหนดเอง
นอกเหนือจากคำอธิบายประกอบในตัวที่จัดทำโดย Java เองแล้ว Java ยังให้ฟังก์ชั่นของการปรับแต่งคำอธิบายประกอบที่กำหนดเอง
วิธีการกำหนดคำอธิบายประกอบคือการใช้คำอธิบายประกอบเพื่อกำหนดคำอธิบายประกอบ คำอธิบายประกอบที่ใช้ในการกำหนดคำอธิบายประกอบเรียกว่าคำอธิบายประกอบเมตา
คำอธิบายประกอบเมตาหลักมีดังนี้: @Target; @retention; @documented; @inherited
1. @Target ระบุว่ามีการใช้คำอธิบายประกอบที่ไหนและอาจใช้กับคลาสวิธีการหรือคุณลักษณะ พารามิเตอร์ ElemenetType ที่เป็นไปได้รวมถึง:
Elemenettype.Constructor Constructor ประกาศ
การประกาศโดเมน Elemenettype.field (รวมถึงอินสแตนซ์ enum)
elemenettype.local_variable ประกาศตัวแปรท้องถิ่น
Elemenettype.method การประกาศวิธีการ
คำสั่งแพ็คเกจ ElemenetType.Package
การประกาศพารามิเตอร์พารามิเตอร์พารามิเตอร์พารามิเตอร์
คลาส ElemenetType.type, อินเตอร์เฟส (รวมถึงประเภทคำอธิบายประกอบ) หรือการประกาศ enum
2. @retention ระบุว่าระดับใดที่จะบันทึกข้อมูลคำอธิบายประกอบ พารามิเตอร์การเก็บรักษาแบบเสริม ได้แก่ :
RetentionPolicy.Source Annotation จะถูกทิ้งโดยคอมไพเลอร์
RetentionPolicy.CLASS คำอธิบายประกอบมีอยู่ในไฟล์คลาส แต่จะถูกยกเลิกโดย VM
RetentionPolicy.runtime VM จะเก็บความคิดเห็นในระหว่างการรันไทม์ดังนั้นข้อมูลคำอธิบายประกอบสามารถอ่านได้ผ่านกลไกการสะท้อนกลับ
3. @documented ไม่ว่าจะรวมคำอธิบายประกอบนี้เมื่อสร้างเอกสารให้รวมคำอธิบายประกอบนี้ใน Javadoc
4. @inherited
ให้คลาสย่อยสืบทอดคำอธิบายประกอบในคลาสหลักดูตัวอย่างคำจำกัดความง่าย ๆ :
คำอธิบายประกอบแพ็คเกจ; นำเข้า java.lang.annotation.documented; นำเข้า java.lang.annotation.ElementType; นำเข้า java.lang.annotation.inherited; นำเข้า java.lang.annotation.retention; นำเข้า java.lang.annotation.RetentionPolicy; นำเข้า java.lang.annotation.target; @Target (ElementType.Method) สาธารณะ @Interface myannotation {ค่าสตริง (); } @retention (RetentionPolicy.Source) @Interface myannotation1 {} @retention (retentionPolicy.class) @interface myannotation2 {} @retention -4. ใช้ตัวอย่าง:
คำอธิบายประกอบแพ็คเกจ; นำเข้า java.lang.annotation.annotation; @myannotation3 ระดับสาธารณะ testannotation {โมฆะคงที่สาธารณะหลัก (สตริง [] args) {// วิธีการที่สร้างขึ้นอัตโนมัติวิธีการเพิ่มความหมายของคำอธิบายประกอบคำอธิบายประกอบของคำอธิบายประกอบและ testannotation.class.getannotation (myannotation3.class); System.out.println (Annotation.toString ()); - พิมพ์ผลลัพธ์: @Annotation.myannotation3 ()
หาก myannotation1 และ myannotation2 ถูกแทนที่ในตัวอย่างข้างต้นค่าของคำอธิบายประกอบที่ได้รับนั้นว่างเปล่าซึ่งเป็นความแตกต่างระหว่างการเก็บรักษา
V. บทบาทของคำอธิบายประกอบ
ณ จุดนี้เราสามารถสรุปบทบาทของคำอธิบายประกอบได้
พื้นฐานสามารถแบ่งออกเป็นสามประเภท:
1. เขียนเอกสาร
2. การวิเคราะห์รหัส
3. การตรวจสอบการรวบรวมอย่างไรก็ตามเฟรมเวิร์กโอเพ่นซอร์สให้ฟังก์ชั่นมากขึ้นเช่น:
ไฮเบอร์เนตการกำหนดค่าคำอธิบายประกอบ
@Column ("AA") สตริงส่วนตัว xx; สิ่งนี้คล้ายกับการกำหนดค่า XML ซึ่งทำให้การกำหนดค่าในโปรแกรมง่ายขึ้นและย้ายส่วนหนึ่งของข้อมูลเมตาจากไฟล์ XML ไปยังรหัสและจัดการและดูแลรักษาไว้ในที่เดียว
มันถูกนำไปใช้ภายในอย่างไร? - กลไกการสะท้อนกลับของ Java คล้ายกับตัวอย่างข้างต้น
ความเห็น
แม้ว่าคำอธิบายประกอบและความคิดเห็นจะแตกต่างกันเพียงคำเดียว แต่การใช้งานนั้นแตกต่างกันมาก
ประโยคเดียวกันนั้นเป็นจริงคำอธิบายประกอบนั้นมีไว้เพื่อให้คอมไพเลอร์ดูและคำอธิบายประกอบนั้นสำหรับคนที่จะเห็น
ขึ้นอยู่กับสิ่งนี้สำหรับวิธีการ:
1. เพียงแค่อธิบายฟังก์ชั่นของวิธีนี้อย่างชัดเจนอินพุตและเอาต์พุต คุณสามารถเพิ่มข้อมูลเพิ่มเติมเช่นผู้เขียนและเวอร์ชัน
2. ทำสองสิ่งนี้ด้วยการจัดแสดงความคิดเห็นที่สวยงาม ตัวอย่างเช่น:
/*************************************************************************************************************************************************************************************** -
ดูเหมือนว่านี่เป็นโน้ตที่ดี ^^
แต่สำหรับภาษา Java ความคิดเห็นจะได้รับฟังก์ชั่นเพิ่มเติม นั่นคือคุณสามารถใช้ฟังก์ชัน Javadoc เพื่อส่งออกความคิดเห็นในรหัสไปยังไฟล์ HTML
หากรหัสของคุณเป็นรหัสที่มีความธรรมดาสูงเอกสารนี้เป็นเอกสารอ้างอิง API คล้ายกับ Java API
ดังนั้นในการสร้างเอกสารดังกล่าวคุณต้องทำตามข้อกำหนดของคำอธิบายประกอบบางอย่างที่กำหนดโดย Java เพื่อสร้างเอกสารมาตรฐาน
1. ความคิดเห็นมาตรฐานเกี่ยวกับวิธีการคลาส Java
เริ่มต้นด้วยความคิดเห็นเกี่ยวกับวิธีการเรียน
/*** อ่านบรรทัดของข้อความ สายจะถูกพิจารณาว่าถูกยกเลิกโดยหนึ่ง * ของฟีดบรรทัด ('/n'), การคืนค่าการขนส่ง ('/r') หรือการคืนค่าการขนส่ง * ตามด้วย linefeed ทันที * * @param ไม่รู้ตัว 1 ถ้าเป็นจริง 'ถัดไป'/n 'จะถูกข้าม <pre code_snippet_id = "74911" snippet_file_name = "blog_20131120_2_8365599" name = "รหัส"> * @param อักขระการเลิกจ้างบรรทัดหรือเป็นโมฆะหากสิ้นสุด * สตรีม * * * * @See Java.IO.LineNumberReader#readline () * * @Exception ioException หากเกิดข้อผิดพลาด I/O *// (อย่าให้ความสนใจกับความหมายของความคิดเห็นข้างต้นเพียงแค่มุ่งเน้นไปที่รูปแบบของคำจำกัดความ)
1. ก่อนอื่นดูที่ด้านบน "อ่านบรรทัดข้อความบรรทัด .. " ย่อหน้านี้เป็นคำอธิบายของวิธีนี้
ส่วนก่อนช่วงแรกซึ่งเป็น "อ่านบรรทัดข้อความ" จะปรากฏใน "วิธีการสรุป"
2. @Param กำหนดพารามิเตอร์อินพุตของวิธีการซึ่ง (สามารถเพิ่มหลายรายการ) ปรากฏใน "รายละเอียดวิธีการ" (คำอธิบายพารามิเตอร์และพารามิเตอร์ถูกคั่นด้วยช่องว่างและแปลงเป็น - ในเอกสารที่สร้างขึ้น)
3. @return คำอธิบายของค่าส่งคืน
4. @See คำอธิบายอ้างอิง
5. คำอธิบายของ @exception ที่ถูกโยนโดยข้อยกเว้นนั้นสวยงาม แท็กประเภทต่าง ๆ สามารถแสดงในบรรทัดเดียวเช่น @param และ @return ล้างโดยตรงหนึ่งบรรทัด
2. ความคิดเห็นมาตรฐานคลาส Java
รูปแบบของคำอธิบายประกอบคลาสและคำอธิบายประกอบของวิธีนั้นเหมือนกัน อะไรคือความแตกต่าง:
1. ตำแหน่งแตกต่างกัน คำอธิบายประกอบชั้นเรียนอยู่เหนือคำจำกัดความของคลาสและคำอธิบายประกอบของวิธีจะอยู่เหนือคำจำกัดความของวิธีการ
2. การเปรียบเทียบคำอธิบายประกอบคลาสใช้แท็กเช่น @Version @author @Since
ดูเทมเพลต
/** จะบัฟเฟอร์อินพุตจากไฟล์ที่ระบุ โดยไม่มีการบัฟเฟอร์การเรียกใช้การอ่าน () หรือ readline () แต่ละครั้งอาจทำให้ไบต์ที่จะอ่านจากไฟล์ * แปลงเป็นอักขระแล้วส่งคืนซึ่งอาจเป็น * โดยธรรมชาติ * * คำอธิบายการทดสอบ * * <p> โปรแกรมที่ใช้ datainputStreams สำหรับการป้อนข้อมูลข้อความสามารถแปลได้โดย * แทนที่แต่ละ datainputStream ด้วย bufferedreader ที่เหมาะสม * * @See Filereader * @SEE INPUTSTREAMREADER * * @Version 0.1, 11/20/13 * @Author OSCAR999 * @Since JDK1.5 *//
เอฟเฟกต์ที่แสดงใน DOC คือ:
ในทำนองเดียวกันประโยคแรกของคำอธิบายจะปรากฏใน "classary"
รายละเอียดของชั้นเรียนจะแสดงดังนี้:
เป็นที่น่าสังเกตว่าการใช้ <p> ในคำอธิบาย หากไม่ได้เพิ่ม <p> ไม่ว่าจะมีบรรทัดใหม่ในรหัส Java เอกสารที่สร้างขึ้นจะไม่ใหม่ หากเพิ่ม <p> บรรทัดใหม่จะปรากฏใน DOC
3. อาหารเสริม
เพื่อเพิ่มวิธีการสร้าง Javadoc:
1. วิธีการบรรทัดชื่อ: พารามิเตอร์ Javadoc +
2. ใช้ Eclipse IDE เพื่อส่งออกหากอยู่ใน Eclipse IDE คลิกขวาบนไฟล์ต้นฉบับหรือโครงการเลือก Export --->
Java -> Javadoc สามารถสร้างได้