C #에서 인터페이스 및 구현 주석을 동기화하는 방법

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과 함께 배포 할 수 있습니다. 문서 파일 (CHM 등).

---

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

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

You have a documented interface method. Implement this interface in a class, press the GhostDoc shortcut key, Ctrl-Shift-D, and the XML comment from the interface will be added to the implemented method.

Go to the Options -> Keyboard settings, and assign a key to GhostDoc.AddIn.RebuildDocumentation (I used Ctrl-Shift-Alt-D).

Now, if you change the XML comment on the interface, just press this shortcut key on the implemented method, and the documentation will be updated. Unfortunately, this doesn't work vice-versa.

---

I usually write comments like this:

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

The methods are used only by the interface, so this comment is not even shown in tooltips when coding.

Edit:

If you want to see docs when you call the class directly and not using the interface, you need to write it twice or use a tool like GhostDoc.

---

Try GhostDoc! It works for me :-)

Edit: Now that I've been made aware of Sandcastle's support for <inheritdoc/>, I endorse Noldorin's post. It's a much better solution. I still recommend GhostDoc on a general basis, though.

---

I have a better answer: FiXml., I'm one of its authors

Cloning the is certainly working approach, but it has significant disadvantages, e.g.:

• When the original comment is changed (which frequently happens during development), its clone is not.
• You're producing huge amount of duplicates. If you're using any source code analysis tools (e.g. Duplicate Finder in Team City), it will find mainly your comments.

As it was mentioned, there is <inheritdoc> tag in Sandcastle, but it has few disadvantages in comparison to FiXml:

• Sandcastle produces compiled HTML help files - normally it does not modify .xml files containing extracted XML comments (at last, this can't be done "on the fly" during the compilation).
• Sandcastle's implementation is less powerful. E.g. the is no <see ... copy="true" />.

See Sandcastle's <inheritdoc> description for further details.

Short description of FiXml: it is a post-processor of XML documentation produced by C# \ Visual Basic .Net. It is implemented as MSBuild task, so it's quite easy to integrate it to any project. It addresses few annoying cases related to writing XML documentation in these languages:

• No support for inheriting the documentation from base class or interface. I.e. a documentation for any overridden member should be written from scratch, although normally it’s quite desirable to inherit at least the part of it.
• No support for insertion of commonly used documentation templates, such as “This type is singleton - use its <see cref="Instance" /> property to get the only instance of it.”, or even “Initializes a new instance of <CurrentType> class.”

To solve mentioned issues, the following additional XML tags are provided:

• <inheritdoc />, <inherited /> tags
• <see cref="..." copy="..." /> attribute in <see/> tag.

Here is its web page and download page.

---

/// <inheritDoc/>

Read here

Use this

---

I built a library to post-process the XML documentation files to add support for the <inheritdoc/> tag.

While it doesn't help with Intellisense in source code, it does allow the modified XML documentation files to be included in a NuGet package and therefore works with Intellisense in referenced NuGet packages.

More info at www.inheritdoc.io (free version available).

---

Don't do that. Think of it this way - if both comments are required to be the same all the time, then one of them isn't necessary. There has to be a reason for the comment (besides some kind of weird obligation to comment-block every function and variable) so you need to figure out what that unique reason is and document that.

---

With ReSharper you can copy it, but I don't think that it is in sync all the time.

참고URL : https://stackoverflow.com/questions/824007/ways-to-synchronize-interface-and-implementation-comments-in-c-sharp