การสืบทอดความคิดเห็นสำหรับ C # (จริงๆแล้วภาษาใดก็ได้)

สมมติว่าฉันมีอินเทอร์เฟซนี้

public interface IFoo
{
    ///<summary>
    /// Foo method
    ///</summary>
    void Foo();

    ///<summary>
    /// Bar method
    ///</summary>
    void Bar();

    ///<summary>
    /// Situation normal
    ///</summary>
    void Snafu();
}

และชั้นนี้

public class Foo : IFoo
{
    public void Foo() { ... }
    public void Bar() { ... }
    public void Snafu() { ... }
}

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

เพราะฉันเกลียดการเขียนความคิดเห็นเดิมซ้ำสำหรับคลาสย่อยที่ได้รับแต่ละคลาส!

GhostDocทำอย่างนั้น สำหรับวิธีการที่ไม่ได้รับการสืบทอดมานั้นจะพยายามสร้างคำอธิบายจากชื่อ

FlingThing() กลายเป็น "Flings the Thing"

คุณสามารถใช้<inheritdoc />แท็กได้ตลอดเวลา:

public class Foo : IFoo
{
    /// <inheritdoc />
    public void Foo() { ... }
    /// <inheritdoc />
    public void Bar() { ... }
    /// <inheritdoc />
    public void Snafu() { ... }
}

เมื่อใช้crefแอตทริบิวต์นี้คุณสามารถอ้างถึงสมาชิกที่แตกต่างกันโดยสิ้นเชิงในคลาสหรือเนมสเปซที่แตกต่างกันโดยสิ้นเชิง!

public class Foo
{
    /// <inheritdoc cref="System.String.IndexOf" />
    public void Bar() { ... } // this method will now have the documentation of System.String.IndexOf
}

ใช้/// <inheritdoc/>ถ้าคุณต้องการมรดก หลีกเลี่ยง GhostDoc หรืออะไรทำนองนั้น

ฉันยอมรับว่าเป็นเรื่องน่ารำคาญที่ความคิดเห็นไม่ได้รับการสืบทอด มันจะเป็นส่วนเสริมที่ค่อนข้างง่ายในการสร้างถ้ามีคนมีเวลา (ฉันหวังว่าฉันจะทำ)

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

GhostDoc เป็นการเริ่มต้นที่ดีและทำให้กระบวนการเขียนความคิดเห็นง่ายขึ้น เป็นประโยชน์อย่างยิ่งในการทำให้ความคิดเห็นเป็นปัจจุบันเมื่อคุณเพิ่ม / ลบพารามิเตอร์เรียกใช้ GhostDoc ใหม่และจะอัปเดตคำอธิบาย

Java มีสิ่งนี้และฉันใช้มันตลอดเวลา แค่ทำ:

/**
 * {@inheritDoc}
 */

และเครื่องมือ Javadoc ก็คิดออก

C # มีเครื่องหมายคล้ายกัน:

<inheritDoc/>

คุณสามารถอ่านเพิ่มเติมได้ที่นี่:

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

ฉันจะบอกว่าให้ใช้ไฟล์

/// <inheritdoc cref="YourClass.YourMethod"/>  --> For methods inheritance

และ

/// <inheritdoc cref="YourClass"/>  --> For directly class inheritance

คุณต้องใส่ความคิดเห็นนี้ไว้ในบรรทัดก่อนหน้าของคลาส / วิธีการของคุณ

สิ่งนี้จะได้รับข้อมูลความคิดเห็นของคุณเช่นจากอินเทอร์เฟซที่คุณได้บันทึกไว้เช่น:

    /// <summary>
    /// This method is awesome!
    /// </summary>
    /// <param name="awesomeParam">The awesome parameter of the month!.</param>
    /// <returns>A <see cref="AwesomeObject"/> that is also awesome...</returns>
    AwesomeObject CreateAwesome(WhateverObject awesomeParam);

Resharper มีตัวเลือกในการคัดลอกข้อคิดเห็นจากคลาสพื้นฐานหรืออินเทอร์เฟซ

อีกวิธีหนึ่งคือการใช้<see />แท็กเอกสาร XML นี่เป็นความพยายามพิเศษ แต่ได้ผลนอกกรอบ ...

นี่คือตัวอย่างบางส่วน:

/// <summary>
/// Implementation of <see cref="IFoo"/>.
/// </summary>
public class Foo : IFoo
{
    /// <summary>
    /// See <see cref="IFoo"/>.
    /// </summary>
    public void Foo() { ... }

    /// <summary>
    /// See <see cref="IFoo.Bar"/>
    /// </summary>
    public void Bar() { ... }

    /// <summary>
    /// This implementation of <see cref="IFoo.Snafu"/> uses the a caching algorithm for performance optimization.
    /// </summary>
    public void Snafu() { ... }
}

อัปเดต:

ตอนนี้ฉันชอบใช้/// <inheritdoc/>ซึ่งตอนนี้รองรับโดย ReSharper

ฉันลงเอยด้วยการสร้างเครื่องมือเพื่อโพสต์กระบวนการไฟล์เอกสาร XML เพื่อเพิ่มการสนับสนุนสำหรับการแทนที่<inheritdoc/>แท็กในไฟล์เอกสาร XML ด้วยตัวเอง มีจำหน่ายที่www.inheritdoc.io (มีเวอร์ชันฟรี)

มีวิธีแก้ปัญหาแบบเนทีฟชนิดหนึ่งที่ฉันพบสำหรับ. NET Core 2.2

แนวคิดคือการใช้<include>แท็ก

คุณสามารถเพิ่ม<GenerateDocumentationFile>true</GenerateDocumentationFile>ของคุณ.csprojไฟล์

คุณอาจมีอินเทอร์เฟซ:

namespace YourNamespace
{
    /// <summary>
    /// Represents interface for a type.
    /// </summary>
    public interface IType
    {
        /// <summary>
        /// Executes an action in read access mode.
        /// </summary>
        void ExecuteAction();
    }
}

และสิ่งที่สืบทอดมาจากมัน:

using System;

namespace YourNamespace
{
    /// <summary>
    /// A type inherited from <see cref="IType"/> interface.
    /// </summary>
    public class InheritedType : IType
    {
        /// <include file='bin\Release\netstandard2.0\YourNamespace.xml' path='doc/members/member[@name="M:YourNamespace.IType.ExecuteAction()"]/*'/>
        public void ExecuteAction() => Console.WriteLine("Action is executed.");
    }
}

โอเคมันค่อนข้างน่ากลัว แต่มันเพิ่มองค์ประกอบที่คาดหวังให้กับไฟล์YourNamespace.xml.

หากคุณสร้างDebugการกำหนดค่าคุณสามารถสลับReleaseสำหรับDebugในfileแอตทริบิวต์ของincludeแท็ก

เพื่อหาที่ถูกต้องmemberคือnameการอ้างอิงเพียงแค่สร้างเปิดDocumentation.xmlไฟล์

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

ด้านสว่างคือ Visual Studio ตรวจสอบความถูกต้องขององค์ประกอบที่คัดลอกดังนั้นจึงง่ายกว่ามากในการเก็บเอกสารและโค้ดให้ซิงค์กับอินเทอร์เฟซ / คลาสฐาน ฯลฯ (เช่นชื่อของอาร์กิวเมนต์ชื่อพารามิเตอร์ชนิด ฯลฯ )

ในโครงการของฉันฉันได้ลงเอยด้วยทั้ง<inheritdoc/>(สำหรับ DocFX) และ<include/>(สำหรับการเผยแพร่แพ็คเกจ NuGet และสำหรับการตรวจสอบที่ Visual Studio):

        /// <inheritdoc />
        /// <include file='bin\Release\netstandard2.0\Platform.Threading.xml' path='doc/members/member[@name="M:Platform.Threading.Synchronization.ISynchronization.ExecuteReadOperation(System.Action)"]/*'/>
        public void ExecuteReadOperation(Action action) => action();