คำถามติดแท็ก documentation-generation

4
BDD เขียนได้จริง ๆ โดยผู้ที่ไม่ใช่โปรแกรมเมอร์หรือไม่?
การพัฒนาพฤติกรรมที่ขับเคลื่อนด้วยสัญลักษณ์ของสถานการณ์“ ที่ได้รับเมื่อนั้น” ได้รับการเน้นย้ำอย่างมากสำหรับการใช้ที่เป็นไปได้ในฐานะวัตถุขอบเขตสำหรับการประเมินการทำงานของซอฟต์แวร์ ฉันยอมรับอย่างแน่นอนว่าGherkinหรือสคริปต์การกำหนดคุณสมบัติที่คุณต้องการเป็นDSL ที่สามารถอ่านได้ทางธุรกิจและมอบคุณค่าเช่นนี้แล้ว อย่างไรก็ตามฉันไม่เห็นด้วยที่จะไม่สามารถเขียนโปรแกรมได้ (เช่นMartin Fowler ) ใครบ้างมีบัญชีของสถานการณ์ที่เขียนโดยไม่ใช่โปรแกรมเมอร์แล้ว instrumented โดยนักพัฒนา หากมีความเห็นพ้องต้องกันเกี่ยวกับการขาดความสามารถในการเขียนคุณจะเห็นปัญหากับเครื่องมือที่แทนที่จะเริ่มต้นด้วยสถานการณ์และการใช้เครื่องมือพวกเขาจะสร้างสถานการณ์ที่สามารถอ่านได้ทางธุรกิจจากการทดสอบจริงหรือไม่ อัปเดต:เกี่ยวกับเครื่องมือ“ ตัวสร้างสถานการณ์จำลอง” แน่นอนว่ามันจะไม่เดาภาษาธุรกิจอย่างน่าอัศจรรย์;) แต่เหมือนกับที่เราใช้ regexp matchers ในการสร้างแบบทดสอบจากบนลงล่าง (ในมิติที่เป็นนามธรรม) เราสามารถใช้ ผู้สร้างสตริงเพื่อสร้างสถานการณ์ในแนวทางจากล่างขึ้นบน ตัวอย่าง“ เพื่อให้ความคิดเท่านั้น”: Given I am on page ${test.currentPage.name} And I click on element ${test.currentAction.element} …

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

1
ทำสำเนาเอกสารเกี่ยวกับการใช้งานอินเตอร์เฟส / แทนที่ดีหรือไม่ดี?
ดังนั้นเราจึงมีส่วนต่อประสานเช่นนั้น /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos /// </summary> void Create(Foo foo); /// <summary> /// Does Bar stuff /// </summary> void Bar(); } เมื่อเร็ว ๆ นี้เราได้เล่นเรื่องเอกสารที่เกี่ยวข้องกับการสร้างและตรวจสอบให้แน่ใจว่ามีเอกสาร XML มากมายดังกล่าวข้างต้น สิ่งนี้ทำให้เกิดเอกสารซ้ำซ้อนมากมาย ตัวอย่างการนำไปใช้: /// <summary> /// A Foo …

8
จะใส่เอกสารรหัสได้ที่ไหน
ขณะนี้ฉันใช้สองระบบเพื่อเขียนเอกสารรหัส (กำลังใช้ C ++): เอกสารเกี่ยวกับวิธีการและสมาชิกคลาสจะถูกเพิ่มถัดจากรหัสโดยใช้รูปแบบ Doxygen บนเซิร์ฟเวอร์ Doxygen ทำงานบนแหล่งข้อมูลเพื่อให้สามารถเห็นผลลัพธ์ในเว็บเบราว์เซอร์ หน้าภาพรวม (อธิบายชุดของคลาสโครงสร้างของแอปพลิเคชันรหัสตัวอย่าง ... ) จะถูกเพิ่มไปยังวิกิ ฉันคิดว่าวิธีนี้ง่ายมากเพราะเอกสารเกี่ยวกับสมาชิกและคลาสนั้นใกล้เคียงกับโค้ดจริง ๆ ในขณะที่หน้าภาพรวมนั้นง่ายต่อการแก้ไขใน Wiki (และยังง่ายต่อการเพิ่มรูปภาพตาราง ... ) เว็บเบราว์เซอร์ช่วยให้คุณดูเอกสารทั้งสอง ตอนนี้เพื่อนร่วมงานของฉันแนะนำให้ใส่ทุกอย่างใน Doxygen เพราะเราสามารถสร้างไฟล์ช่วยเหลือขนาดใหญ่หนึ่งไฟล์พร้อมทุกสิ่งในนั้น (โดยใช้ HTML WorkShop หรือ Qt Assistant ของ Microsoft) ความกังวลของฉันคือการแก้ไขเอกสารสไตล์ Doxygen นั้นยากกว่ามาก (เมื่อเทียบกับ Wiki) โดยเฉพาะเมื่อคุณต้องการเพิ่มตารางรูปภาพ ... (หรือมีเครื่องมือ 'ดูตัวอย่าง' สำหรับ Doxygen ที่ไม่ต้องการให้คุณสร้าง รหัสก่อนที่คุณจะเห็นผลลัพธ์ได้หรือไม่) โครงการโอเพ่นซอร์สขนาดใหญ่ (หรือซอร์สปิด) อะไรที่ใช้ในการเขียนเอกสารรหัส? พวกเขายังแยกสิ่งนี้ระหว่าง …

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

5
อะไรคือสิ่งที่มอบให้ลูกค้าสำหรับเว็บแอปพลิเคชัน [ปิด]
ปิด คำถามนี้จะต้องมีมากขึ้นมุ่งเน้น ไม่ยอมรับคำตอบในขณะนี้ ต้องการปรับปรุงคำถามนี้หรือไม่ อัปเดตคำถามเพื่อให้มุ่งเน้นที่ปัญหาเดียวโดยแก้ไขโพสต์นี้ ปิดให้บริการใน4 ปีที่แล้ว ฉันได้ทำเว็บแอพพลิเคชั่นเสร็จแล้วซึ่งพัฒนาโดยทั่วไปใน PHP และเป็นอีกเว็บแอปพลิเคชั่นปกติ โดยปกติเมื่อฉันส่งมอบการผลิตครั้งสุดท้ายฉันเพิ่งส่งเอกสารรหัสและข้อมูลสถาปัตยกรรมให้กับลูกค้า อย่างไรก็ตามสำหรับโครงการนี้ลูกค้ายืนยันว่ามีข้อมูลที่สมบูรณ์เกี่ยวกับโครงการ ดังนั้นฉันแค่สงสัยว่า ... อะไรคือเอกสารด้านเทคนิคและไม่ใช่ด้านเทคนิคที่บังคับที่ฉันสามารถมอบให้กับลูกค้าของฉันนอกเหนือจากรหัสและเอกสารทางสถาปัตยกรรม? (นอกจากนี้ยังเป็นการดีที่จะตีลูกค้าเกี่ยวกับสถิติและข้อมูลต่าง ๆ เกี่ยวกับโครงการเพื่อที่เขาจะได้ทราบปริมาณงานที่เกี่ยวข้องและความยอดเยี่ยมของผลิตภัณฑ์จริง ๆ )

1
doxygen รองรับเทมเพลตสำหรับเอาต์พุต HTML หรือไม่
ฉันได้บันทึกรหัสไว้doxygenแล้ว แต่ฉันไม่ต้องการ HTML ที่เป็นค่าเริ่มต้น ฉันรู้ว่าฉันสามารถปรับแต่งได้ด้วยการให้ CSS หัวกระดาษท้ายกระดาษ ฯลฯ (เช่น GNOME) และฉันจะเพิ่มรหัส PHP ทั่วไปลงในไฟล์และบอกให้บันทึกได้.phpแต่นั่นไม่ใช่สิ่งที่ฉันต้องการจริงๆ . สิ่งที่ฉันต้องการคือผลลัพธ์เช่น MSDN ฉันไม่สามารถอธิบายได้จริงๆ คำถามของฉันคือมีความเป็นไปได้ในการใช้ doxygen กับบางสิ่งบางอย่างเช่นเทมเพลตหรือฉันต้องแสดงผล XML และแยกมันด้วยโปรแกรมอื่น
โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.