C #에 대한 주석 상속 (실제로 모든 언어)

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() { ... }
}

---

/// <inheritdoc/>상속을 원하는 경우 사용하십시오 . GhostDoc 또는 이와 유사한 것을 피하십시오.

댓글이 상속되지 않는다는 것이 귀찮다는 데 동의합니다. 누군가가 시간을 가졌다면 만드는 것은 상당히 간단한 추가 기능 일 것입니다.

즉, 코드베이스에서 인터페이스에만 XML 주석을 넣고 클래스에 추가 구현 주석을 추가합니다. 이것은 우리의 클래스가 비공개 / 내부이고 인터페이스 만 공개되기 때문에 우리에게 효과적입니다. 인터페이스를 통해 객체를 사용할 때마다 전체 주석이 지능적으로 표시됩니다.

GhostDoc은 좋은 시작이며 프로세스를 주석 작성하기 쉽게 만들었습니다. 매개 변수를 추가 / 제거하고 GhostDoc을 다시 실행하고 설명을 업데이트 할 때 주석을 최신 상태로 유지하는 것이 특히 유용합니다.

---

Java에는이 기능이 있으며 항상 사용합니다. 그냥 해:

/**
 * {@inheritDoc}
 */

그리고 Javadoc 도구가이를 파악합니다.

C #에는 비슷한 마커가 있습니다.

<inheritDoc/>

여기에서 자세한 내용을 읽을 수 있습니다.

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

---

Resharper에는 기본 클래스 또는 인터페이스에서 주석을 복사하는 옵션이 있습니다.

---

나는 직접 사용한다고 말할 것입니다

/// <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);

---

또 다른 방법은 <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에서 지원 하는 것을 사용 하는 것을 선호합니다 .

---

결국 <inheritdoc/>XML 문서 파일 자체 의 태그 교체 지원을 추가하기 위해 XML 문서 파일을 사후 처리하는 도구를 만들었습니다 . www.inheritdoc.io 에서 사용 가능 (무료 버전 사용 가능).

---

글쎄, .NET Core 2.2에 대한 일종의 기본 솔루션이 있습니다.

아이디어는 <include>태그 를 사용하는 것입니다 .

파일을 추가 <GenerateDocumentationFile>true</GenerateDocumentationFile>할 수 있습니다 .csproj.

You might have an interface:

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

And something that inherits from it:

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.");
    }
}

Ok, it is a bit scary, but it does add the expected elements to the YourNamespace.xml.

If you build Debug configuration, you can swap Release for Debug in the file attribute of include tag.

To find a correct member's name to reference just open generated Documentation.xml file.

I also assume that this approach requires a project or solution to be build at least twice (first time to create an initial XML file, and the second time to copy elements from it to itself).

The bright side is that Visual Studio validates copied elements, so it is much easier to keep documentation and code in sync with interface/base class, etc (for example names of arguments, names of type parameters, etc).

At my project, I have ended up with both <inheritdoc/> (for DocFX) and <include/> (For publishing NuGet packages and for validation at 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();

참고URL : https://stackoverflow.com/questions/342964/comment-inheritance-for-c-sharp-actually-any-language