คำถามติดแท็ก javadocs

เมื่อไม่นานมานี้ฉันกำลังทำงานเกี่ยวกับการปรับโครงสร้างส่วนต่าง ๆ ของรหัสที่ฉันกำลังทำอยู่ไม่เพียง แต่จะเข้าใจตัวเองดีขึ้น แต่ยังทำให้ผู้อื่นที่ทำงานกับรหัสนั้นง่ายขึ้น ฉันมักจะพึ่งพาด้านของความคิดที่ว่าตนเอง documenting รหัสเป็นสิ่งที่ดี ฉันแค่คิดว่ามันสะอาดและถ้ารหัสพูดสำหรับตัวเองดี ... ที่ดี ในอีกทางหนึ่งเรามีเอกสารเช่น javadocs ฉันชอบสิ่งนี้เช่นกัน แต่มีความเสี่ยงบางอย่างที่ความคิดเห็นที่นี่ล้าสมัย (เช่นเดียวกับความคิดเห็นทั่วไป) อย่างไรก็ตามหากพวกเขาทันสมัยพวกเขาจะมีประโยชน์อย่างมากในการพูดทำความเข้าใจกับอัลกอริทึมที่ซับซ้อน อะไรคือแนวทางปฏิบัติที่ดีที่สุดสำหรับสิ่งนี้ คุณวาดเส้นระหว่างรหัสการทำเอกสารด้วยตนเองและ javadocs ได้อย่างไร

18 java  documentation  refactoring  javadocs 

มีคำที่ดีที่คล้ายกัน แต่แตกต่างจาก "คัดค้าน" เพื่อหมายความว่าวิธีการหรือ API อยู่ในรหัสฐาน แต่ไม่ควรใช้เนื่องจากการใช้งานไม่สมบูรณ์หรือมีแนวโน้มที่จะเปลี่ยนแปลง? (ใช่ฉันรู้วิธีการเหล่านั้นไม่ควรเปิดเผยต่อสาธารณชน yada yada yada ฉันไม่ได้สร้างสถานการณ์ของฉันฉันแค่พยายามทำให้ดีที่สุดเท่าที่จะทำได้) ผู้คนแนะนำอะไร ทดลองไม่สมบูรณ์มีอะไรอีกหรือ หากฉันกำลังสร้างเอกสาร javadoc สำหรับ API นี้ที่ยังอยู่ในฟลักซ์ฉันควรใช้แท็ก @deprecated หรือมีข้อตกลงที่ดีกว่า สำหรับฉัน @deprecated แสดงว่า API นี้เก่าและมีกลไกที่ต้องการที่ใหม่กว่าพร้อมใช้งาน ในสถานการณ์ของฉันไม่มีทางเลือก แต่วิธีการบางอย่างใน API ยังไม่เสร็จสิ้นและไม่ควรใช้ ณ จุดนี้ฉันไม่สามารถทำให้พวกเขาเป็นส่วนตัว แต่ฉันต้องการที่จะใส่คำเตือนที่ชัดเจนในเอกสาร

12 documentation  terminology  api  documentation-generation  javadocs 

ใน JavaDoc เพื่อX509Certificate getSubjectDN()ระบุ: denigratedแทนที่ด้วย getSubjectX500Principal () ฉันเคยเห็นเลิกใช้ในวิธีการที่ไม่ควรใช้อีกต่อไป แต่ไม่ได้ลบล้าง ฉันพบรายงานข้อผิดพลาดเกี่ยวกับกรณีนี้โดยเฉพาะซึ่งปิดด้วยความคิดเห็น: นี่ไม่ใช่ข้อผิดพลาด "เลิกใช้แล้ว" มีไว้เพื่อใช้ในกรณีที่ร้ายแรงเท่านั้น เมื่อเรากำลังใช้เมธอดที่ถูกคัดค้านการดำเนินการที่แนะนำทั่วไปคือการหยุดใช้เมธอด ดังนั้นสิ่งที่เป็นปัญหาเมื่อการดำเนินการวิธีการที่ถูกทำเครื่องหมายเป็นdenigrated ?

11 java  terminology  javadocs 

ฉันกำลังทำงานในห้องสมุดขนาดเล็กที่ให้การใช้งานของตัวชี้วัดสตริงพื้นฐานที่รู้จักกันดี ส่วนใหญ่เพื่อการศึกษาของฉันเอง ดังนั้นการพัฒนาจึงเกิดขึ้นทุกครั้งที่ฉันมีเวลาว่าง ด้วยเหตุนี้ฉันจึงเป็นกระบวนการอัตโนมัติโดยอัตโนมัติดังนั้นฉันจึงสามารถเผยแพร่เวอร์ชันได้บ่อยเท่าที่ฉันทำงานโดยไม่ต้องใช้ความพยายามมากเกินไป อย่างไรก็ตามการบำรุงรักษาเอกสาร 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, …

9 java  documentation  javadocs 

ฉันต้องการเขียน Javadoc ด้วยวิธี DRY แต่เอกสาร oracle เกี่ยวกับJavadocกล่าวว่าเขียนสิ่งเดียวกันอีกครั้งในความคิดเห็นของเมธอด overload ฉันไม่สามารถหลีกเลี่ยงการทำซ้ำได้หรือไม่

9 documentation  comments  dry  javadocs