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

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

/// <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에서 지원하는 것을 선호합니다 .

결국 <inheritdoc/>XML 문서 파일 자체 의 태그 교체 지원을 추가하기 위해 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();