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를 툴팁에서 작동하지 않습니다.

당신의 아이디어를 공유하십시오.

감사.

Microsoft Sandcastle (또는 NDoc) inheritdoc태그를 사용하면이 작업을 매우 쉽게 수행 할 수 있습니다 . 사양에서 공식적으로 지원하지는 않지만 사용자 정의 태그는 완벽하게 허용되며 실제로 Microsoft는 Sandcastle을 만들 때 NDoc에서이 태그 (및 다른 하나 또는 두 개의 태그)를 복사하기로 선택했습니다.

/// <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)
{
    //
}

다음 은 사용법을 자세히 설명하는 Sandcastle Help File Builder GUI의 도움말 페이지입니다.

(물론, 이것은 귀하의 질문에서 언급했듯이 특별히 "동기화"가 아니지만, 그럼에도 불구하고 정확히 찾고있는 것 같습니다.)

참고로, 일부 사람들은 파생 및 구현 된 클래스에서 주석을 항상 다시 지정해야한다고 생각하는 것을 보았지만 이것은 나에게 완벽하게 공정한 아이디어처럼 들립니다. (실제로 내 라이브러리 중 하나를 문서화 할 때 직접 해 보았지만 문제가 전혀 발생하지 않았습니다.) 주석이 전혀 다를 이유가 거의 없기 때문에 상속하고 쉬운 방법으로 수행하는 것이 어떻습니까?

편집 : 업데이트와 관련하여 Sandcastle이 처리해 드릴 수도 있습니다. Sandcastle은 입력에 사용하는 실제 XML 파일의 수정 된 버전을 출력 할 수 있습니다. 즉, Visual Studio에서 직접 빌드하는 대신 이 수정 된 버전 을 라이브러리 DLL과 함께 배포 할 수 있습니다. 즉, intellisense에 주석이 있음을 의미합니다. 문서 파일 (CHM 등).

아직 사용하고 있지 않다면 GhostDoc 이라는 무료 Visual Studio 애드온을 강력히 권장합니다 . 문서화 프로세스가 쉬워집니다. 다소 관련된 질문에 대한 내 의견 을 살펴보십시오 .

GhostDoc은 자동으로 동기화하지 않지만 다음 시나리오에서는 도움이 될 수 있습니다.

문서화 된 인터페이스 방법이 있습니다. 클래스에서이 인터페이스를 구현하고 GhostDoc 바로 가기 키를 누르면 인터페이스 Ctrl-Shift-D의 XML 주석이 구현 된 메서드에 추가됩니다.

옵션-> 키보드 설정으로 이동하여 GhostDoc.AddIn.RebuildDocumentation(I used Ctrl-Shift-Alt-D)에 키를 지정하십시오 .

이제 인터페이스 에서 XML 주석을 변경하는 경우 구현 된 메서드에서이 바로 가기 키를 누르기 만하면 설명서가 업데이트됩니다. 불행히도 이것은 그 반대의 경우도 마찬가지입니다.

나는 보통 다음과 같은 주석을 씁니다.

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

이 메서드는 인터페이스에서만 사용되므로이 주석은 코딩 할 때 도구 설명에도 표시되지 않습니다.

편집하다:

인터페이스를 사용 하지 않고 클래스를 직접 호출 할 때 문서를 보려면 문서를 두 번 작성하거나 GhostDoc과 같은 도구를 사용해야합니다.

GhostDoc을 사용해보십시오 ! 그것은 나를 위해 작동합니다 :-)

편집 : 샌드캐슬의에 대한 지원을 알게되었으므로 <inheritdoc/>Noldorin의 게시물을지지합니다. 훨씬 더 나은 솔루션입니다. 그래도 일반적으로 GhostDoc을 권장합니다.

더 나은 대답이 있습니다 : FiXml . , 저자 중 한 명입니다.

복제는 확실히 작동하는 방법이지만 다음과 같은 중요한 단점이 있습니다.

• 원래 주석이 변경되면 (개발 중에 자주 발생) 복제는 변경되지 않습니다.
• 엄청난 양의 중복을 생성하고 있습니다. 소스 코드 분석 도구 (예 : Team City의 Duplicate Finder)를 사용하는 경우 주로 귀하의 의견을 찾습니다.

언급했듯이 Sandcastle 에는 <inheritdoc>태그가 있지만 FiXml에 비해 몇 가지 단점이 있습니다.

• Sandcastle은 컴파일 된 HTML 도움말 파일을 생성합니다. 일반적으로 .xml추출 된 XML 주석이 포함 된 파일을 수정하지 않습니다 (마지막으로 컴파일 중에 "즉시"수행 할 수 없음).
• Sandcastle의 구현은 덜 강력합니다. 예 : 아니오 <see ... copy="true" />.

자세한 내용은 Sandcastle의 <inheritdoc>설명 을 참조 하십시오.

FiXml에 대한 간단한 설명 : C # \ Visual Basic .Net에서 생성 한 XML 문서의 포스트 프로세서입니다. MSBuild 작업으로 구현되므로 모든 프로젝트에 통합하기가 매우 쉽습니다. 다음 언어로 XML 문서 작성과 관련된 몇 가지 성가신 경우를 다룹니다.

• 기본 클래스 또는 인터페이스에서 문서 상속을 지원하지 않습니다. 즉, 재정의 된 멤버에 대한 문서는 처음부터 작성해야하지만 일반적으로 적어도 일부를 상속하는 것이 바람직합니다.
• "이 유형은 싱글 톤입니다. 해당 <see cref="Instance" />속성을 사용 하여 유일한 인스턴스를 가져옵니다."또는 "새 <CurrentType>클래스 인스턴스를 초기화합니다." 와 같이 일반적으로 사용되는 문서 템플릿의 삽입을 지원하지 않습니다 .

언급 된 문제를 해결하기 위해 다음과 같은 추가 XML 태그가 제공됩니다.

• <inheritdoc />, <inherited /> 태그
• <see cref="..." copy="..." /><see/>태그의 속성 .

여기에 웹 페이지 와 다운로드 페이지가 있습니다.

/// <inheritDoc/>

여기에서 읽으십시오

이것을 사용하십시오

<inheritdoc /> 태그에 대한 지원을 추가하기 위해 XML 문서 파일을 사후 처리하는 라이브러리를 구축했습니다.

소스 코드의 Intellisense에는 도움이되지 않지만 수정 된 XML 문서 파일을 NuGet 패키지에 포함 할 수 있으므로 참조 된 NuGet 패키지의 Intellisense와 함께 작동합니다.

자세한 정보는 www.inheritdoc.io (무료 버전 사용 가능)에서 확인하십시오.

그러지 마. 이렇게 생각해보십시오. 두 주석이 항상 동일해야한다면 둘 중 하나는 필요하지 않습니다. 주석에 대한 이유가 있어야합니다 (모든 함수와 변수를 주석으로 차단해야하는 이상한 의무 외에). 따라서 고유 한 이유가 무엇인지 파악하고 문서화해야합니다.

ReSharper를 사용하면 복사 할 수 있지만 항상 동기화되어 있지는 않습니다.