.NET 은 xml 문서속 설명서

Question

NDoc 는 XML element inheritdoc 할 수 있는 상속해 문서의 구성원에서 부모래(또는 구현된 인터페이스).그러나 Visual Studio(i.eC#컴파일러)는 이해하지 못하는 태그의 불평에 대해 설명서를 존재하지 않습니다.그래서 StyleCop 고 다른 어떤 도구입니다.이 있는 다른 방법은?당신은 어떻게 유지에 대한 문서 완벽한,아직 없이 복제 XML 설명은?

Answer 1

한 가지 대안은 사용하는 것입니다 고스트 돔 - 자동으로 의견을 생성하는 Visual Studio 용 추가 기능. 이것은 물론 XML 설명을 복제합니다. 물론 피하려고하는 것의 일부입니다. 그러나 적어도 자동으로 만듭니다.

상속 받거나 인터페이스 메소드를 우선하는 방법에 대해 문서를 완전히 떠나면 어떻게됩니까? NDOC가 구성된 방법에 달려 있다고 생각하지만 MSDN 문서에서는 자연스럽게 문서를 상속받는 것 같습니다. 제안 상속 된 방법을 위해 문서를 구속하지 않으면 vs는 윙윙하지 않습니다. 확실히 시도해 볼 가치가 있습니다.

Answer 2

더 나은 대답: FiXml.

복제 댓글 GhostDoc 노 접근 방식이지만,중요한 단점들,예를 들어:

• 할 때 원래의 의견이 변경되었(는 자주 발생 개발 중), 그것의 복제지 않습니다.
• 당신을 생산의 엄청난 금액을 중복.를 사용하는 경우에는 소스 코드를 분석 도구(예:중복 찾기에서 팀은 도시),니다 주로 찾을 귀하의 의견이다.

의 간단한 설명 FiXml:그것은 포스트-프로세서의 XML 문서를 생성하여 C#\Visual Basic.Net.그것은으로 구현 MSBuild 작업,그래서 아주 쉽게 그것을 통합하는 어떤 프로젝트입니다.그것은 주소가 몇 가지 성가신 경우 작성과 관련된 XML 문서에서 이러한 언어:

• 없음에 대한 지원받아 문서에서는 기본 클래스 또는 인터페이스입니다. I.e.문서에 대한 모든 멤버를 재정의해야 처음부터 쓰여 있지만,일반적으로 그것은 매우 바람직한 상속 적어도 그것의 일부입니다.
• 없음에 대한 지원의 삽입은 일반적으로 사용되는 문서 템플릿, 등"이 유형은 단일 사용의 <see cref="Instance" /> 재산을 얻을만의 인스턴스.", 또는"초기화합의 새 인스턴스 <CurrentType> 클래스입니다."

를 해결하 언급한 문제는 다음과 같은 추가 XML 태그를 제공합니다:

• <inheritdoc />, <inherited /> 태그
• <see cref="..." copy="..." /> 특성 <see/> 태그입니다.

기 웹 페이지의 고 다운로드 페이지 (링크).

마지막으로,거기에 <inheritdoc> 태그 샌드캐슬 -그것은 확실히 더 나은 사용하기보다는 그것을 복사 XML 의견하지만,그것은 몇 가지 단점에서 비교하 FiXml:

• 샌드캐슬을 생산하 컴파일 HTML 도움말 파일을 수정하지 않 .xml 파 이 포함된 추출 XML 다.하지만 이러한 파일을 사용하여 많은 도구 함.NET 반사 클래스고 브라우저\IntelliSense Visual Studio.NET.그래서 사용하는 경우 단지에는 샌드캐슬이 표시되지 않습니다 상속된 설명서가 있다.
• 샌드캐슬의 구현 적은 강력합니다.E.g.은 없 <see ... copy="true" />.

보 샌드캐슬의 <inheritdoc> 설명 에 대한 자세한 내용을 확인할 수 있습니다.

Answer 3

XML 문서화 파일을 후 프로세스하기위한 명령 줄 도구를 구축하여 지원을 추가했습니다.u003Cinheritdoc/> 꼬리표.

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

보다 www.inheritdoc.io 자세한 내용 (무료 버전 사용 가능).