วิธีซิงโครไนซ์อินเทอร์เฟซและความคิดเห็นในการใช้งานใน C # [ปิด]

มีวิธีอัตโนมัติในการซิงค์ความคิดเห็นระหว่างอินเทอร์เฟซและการใช้งานหรือไม่ ฉันกำลังจัดทำเอกสารทั้งคู่และไม่ต้องการให้ซิงค์ด้วยตนเอง

อัพเดท:

พิจารณารหัสนี้:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

เมื่อฉันสร้างชั้นเรียนเช่นนี้:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

ความคิดเห็นที่นี่จะไม่แสดง:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

<inheritDoc/>แท็กที่ดีที่สุดที่จะสร้างเอกสารในปราสาททราย แต่มันไม่ทำงานในคำแนะนำเครื่องมือ IntelliSense

กรุณาแบ่งปันความคิดของคุณ

ขอบคุณ.

คุณสามารถทำได้อย่างง่ายดายโดยใช้inheritdocแท็กMicrosoft Sandcastle (หรือ NDoc) ข้อกำหนดนี้ไม่ได้รับการสนับสนุนอย่างเป็นทางการ แต่แท็กที่กำหนดเองเป็นที่ยอมรับอย่างสมบูรณ์และ Microsoft เลือกที่จะคัดลอกสิ่งนี้ (และแท็กอื่นหนึ่งหรือสองแท็ก) จาก NDoc เมื่อสร้าง Sandcastle

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

นี่คือหน้าความช่วยเหลือจาก GUI ของ Sandcastle Help File Builder ซึ่งอธิบายการใช้งานทั้งหมด

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

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

แก้ไข:เกี่ยวกับการอัปเดตของคุณ Sandcastle ยังสามารถดูแลคุณได้ Sandcastle สามารถส่งออกไฟล์ XML จริงเวอร์ชันแก้ไขที่ใช้สำหรับอินพุตซึ่งหมายความว่าคุณสามารถแจกจ่ายเวอร์ชันที่แก้ไขนี้พร้อมกับ DLL ไลบรารีของคุณแทนเวอร์ชันที่สร้างขึ้นโดยตรงโดย Visual Studio ซึ่งหมายความว่าคุณมีความคิดเห็นใน intellisense เช่นเดียวกับ ไฟล์เอกสาร (CHM อะไรก็ได้)

หากคุณไม่ได้ใช้มันแล้วผมขอแนะนำ addon ของ Visual Studio ฟรีที่เรียกว่าGhostDoc ช่วยลดขั้นตอนการจัดทำเอกสาร ดูความคิดเห็นของฉันเกี่ยวกับคำถามที่เกี่ยวข้อง

แม้ว่า GhostDoc จะไม่ทำการซิงโครไนซ์โดยอัตโนมัติ แต่ก็สามารถช่วยคุณได้ในสถานการณ์ต่อไปนี้:

คุณมีวิธีการเชื่อมต่อแบบเอกสาร ใช้อินเทอร์เฟซนี้ในคลาสกดปุ่มทางลัด GhostDoc Ctrl-Shift-Dและความคิดเห็น XML จากอินเทอร์เฟซจะถูกเพิ่มลงในวิธีการใช้งาน

ไปที่ตัวเลือก ->การตั้งค่าแป้นพิมพ์และกำหนดคีย์ให้กับGhostDoc.AddIn.RebuildDocumentation(ฉันเคยใช้Ctrl-Shift-Alt-D)

ตอนนี้หากคุณเปลี่ยนความคิดเห็น XML บนอินเทอร์เฟซเพียงแค่กดปุ่มทางลัดนี้บนวิธีการใช้งานและเอกสารจะได้รับการอัปเดต น่าเสียดายที่สิ่งนี้ใช้ไม่ได้ในทางกลับกัน

ฉันมักจะเขียนความคิดเห็นในลักษณะนี้:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

วิธีการนี้ใช้โดยอินเทอร์เฟซเท่านั้นดังนั้นความคิดเห็นนี้จึงไม่ปรากฏในคำแนะนำเครื่องมือเมื่อเขียนโค้ด

แก้ไข:

หากคุณต้องการดูเอกสารเมื่อคุณเรียกคลาสโดยตรงและไม่ได้ใช้อินเทอร์เฟซคุณต้องเขียนสองครั้งหรือใช้เครื่องมือเช่น GhostDoc

ลองGhostDoc ! มันใช้ได้กับฉัน :-)

แก้ไข:ตอนนี้ฉันได้รับทราบถึงการสนับสนุนของ Sandcastle <inheritdoc/>แล้วฉันรับรองโพสต์ของ Noldorin เป็นทางออกที่ดีกว่ามาก ฉันยังคงแนะนำ GhostDoc โดยทั่วไปแม้ว่า

ผมมีคำตอบที่ดีกว่า: FiXml ฉันเป็นหนึ่งในผู้เขียน

การโคลนนิ่งเป็นแนวทางการทำงานอย่างแน่นอน แต่มีข้อเสียที่สำคัญเช่น:

• เมื่อความคิดเห็นเดิมมีการเปลี่ยนแปลง (ซึ่งมักเกิดขึ้นในระหว่างการพัฒนา) จะไม่มีการโคลน
• คุณกำลังผลิตรายการซ้ำจำนวนมาก หากคุณใช้เครื่องมือวิเคราะห์ซอร์สโค้ดใด ๆ (เช่น Duplicate Finder ใน Team City) จะพบความคิดเห็นของคุณเป็นหลัก

ดังที่ได้กล่าวไปแล้วก็มี <inheritdoc>แท็กในSandcastleแต่มีข้อเสียเล็กน้อยเมื่อเปรียบเทียบกับ FiXml:

• Sandcastle สร้างไฟล์วิธีใช้ HTML ที่คอมไพล์แล้ว - โดยปกติจะไม่แก้ไข .xmlไฟล์ที่มีความคิดเห็น XML ที่แยกออกมา (ในที่สุดก็ไม่สามารถทำได้ "ทันที" ในระหว่างการคอมไพล์)
• การใช้งานของ Sandcastle นั้นมีประสิทธิภาพน้อยกว่า เช่น is no <see ... copy="true" />.

ดู <inheritdoc>คำอธิบายของ Sandcastleสำหรับรายละเอียดเพิ่มเติม

คำอธิบายโดยย่อของ FiXml: เป็นโพสต์โปรเซสเซอร์ของเอกสาร XML ที่สร้างโดย C # \ Visual Basic .Net มันถูกนำไปใช้เป็นงาน MSBuild ดังนั้นจึงค่อนข้างง่ายที่จะรวมเข้ากับโครงการใด ๆ กล่าวถึงกรณีที่น่ารำคาญเล็กน้อยที่เกี่ยวข้องกับการเขียนเอกสาร XML ในภาษาเหล่านี้:

• ไม่รองรับการสืบทอดเอกสารจากคลาสพื้นฐานหรืออินเทอร์เฟซ เช่นเอกสารสำหรับสมาชิกที่ถูกลบล้างควรเขียนตั้งแต่เริ่มต้นแม้ว่าโดยปกติแล้วมันค่อนข้างเป็นที่พึงปรารถนาที่จะสืบทอดอย่างน้อยส่วนหนึ่งของมัน
• ไม่รองรับการแทรกเทมเพลตเอกสารที่ใช้กันทั่วไปเช่น“ ประเภทนี้เป็นแบบซิงเกิลตัน - ใช้<see cref="Instance" />คุณสมบัติเพื่อรับอินสแตนซ์เดียวของมัน” หรือแม้แต่“ เริ่มต้นอินสแตนซ์<CurrentType>คลาสใหม่”

เพื่อแก้ไขปัญหาดังกล่าวมีการจัดเตรียมแท็ก XML เพิ่มเติมดังต่อไปนี้:

• <inheritdoc />, <inherited /> แท็ก
• <see cref="..." copy="..." />แอตทริบิวต์ใน<see/>แท็ก

นี่คือหน้าเว็บและหน้าดาวน์โหลด

/// <inheritDoc/>

อ่านได้ที่นี่

ใช้สิ่งนี้

ฉันสร้างไลบรารีเพื่อโพสต์กระบวนการไฟล์เอกสาร XML เพื่อเพิ่มการสนับสนุนสำหรับแท็ก <inheritdoc />

แม้ว่าจะไม่ช่วย Intellisense ในซอร์สโค้ด แต่ก็อนุญาตให้รวมไฟล์เอกสาร XML ที่แก้ไขไว้ในแพ็คเกจ NuGet และทำงานร่วมกับ Intellisense ในแพ็คเกจ NuGet ที่อ้างอิง

ข้อมูลเพิ่มเติมที่www.inheritdoc.io (มีเวอร์ชันฟรี)

อย่าทำอย่างนั้น คิดอย่างนี้ - ถ้าความคิดเห็นทั้งสองต้องเหมือนกันตลอดเวลาแสดงว่าไม่จำเป็น ต้องมีเหตุผลสำหรับความคิดเห็น (นอกเหนือจากภาระหน้าที่แปลก ๆ บางอย่างในการแสดงความคิดเห็นบล็อกทุกฟังก์ชันและตัวแปร) ดังนั้นคุณต้องหาเหตุผลที่ไม่ซ้ำกันนั้นคืออะไรและจัดทำเอกสารนั้น

ด้วย ReSharper คุณสามารถคัดลอกได้ แต่ฉันไม่คิดว่ามันจะซิงค์ตลอดเวลา