2017-01-18 6 views
7

同じメソッドの複数のオーバーロードを提供する場合、私は多くの場合、DRYに違反し、メンテナンスコストを増大させる方法の説明を繰り返す必要がありコメント:DRY XMLは

/// <summary> 
/// Frobnicates all foos read from the given reader. Frobnication is a 
/// process where ...[lots of text]... 
/// </summary> 
/// <param name="hasBar">[Description of hasBar]</param> 
void FrobnicateFoo(TextReader reader, bool hasBar) 
{ 
    ... 
} 

/// <summary> 
/// Frobnicates all foos read from the given file. Frobnication is a 
/// process where ...[same lots of text]... 
/// </summary> 
/// <param name="hasBar">[Same description of hasBar]</param> 
void FrobnicateFoo(String path, bool hasBar) 
{ 
    ... 
} 

で複数のパラメータ場合、この問題が悪化します同じ目的が繰り返されます(例として「hasBar」が与えられます)。それは図書館の利用者にはあまり便利だし、明らかに

/// <summary> 
/// Frobnicates all foos read from the given reader. Frobnication is a 
/// process where ...[lots of text]... 
/// </summary> 
/// <param name="hasBar">[Description of hasBar]</param> 
void FrobnicateFoo(TextReader reader, bool hasBar) 
{ 
    ... 
} 

/// <summary> 
/// Convenience method which opens the file with a UTF-8 encoding and then 
/// frobnicates all foos, see FrobnicateFoo(TextReader). 
/// </summary> 
void FrobnicateFoo(String path, bool hasBar) 
{ 
    ... 
} 

:私が見つけ

一つの「回避策」は、「参照」その他のドキュメントです。

重複を避けるために使用できる組み込みのメカニズム(またはスマート戦略)がありますかは、自分のメソッドのユーザーにとって使いやすいものですか?私は主にIntelliSenseについて心配していますが、HTMLドキュメントは生成されていません。

+0

私はあなたがそれらをタグとして追加した理由を知っていますが、これはC#またはVB固有の質問ではありません。 –

+0

@DanielShillcock:C#またはVBのみのソリューションであれば問題ありません。 :-) XMLコメントをまったくサポートしていない.NET言語があります(たとえばBooなど)。 – Heinzi

+4

あなたの質問には答えがないと思います。 –

答えて

2

XMLタグを使用したソリューションが実際にあります。実際には、XMLファイルでドキュメンテーションを構築し、メソッドをこのXMLファイルにリンクします。ここで私が作った小さな例があります。ここ

ソリューションはVB.NETであるが、私はC#...

まずに変換し、本当に難しいことではないだろうと思い、あなたは標準ライブラリの定義が必要になります。

''' <summary> 
''' This is my First class 
''' </summary> 
''' <remarks></remarks> 
Public Class FirstClass 
    ''' <summary> 
    ''' This is my first method 
    ''' </summary> 
    ''' <param name="A">A</param> 
    ''' <returns>True</returns> 
    ''' <remarks></remarks> 
    Public Function FirstMethod(A As Integer) As Boolean 
     Return True 
    End Function 

    ''' <include file="DocFile.xml" path="Doc/member[@name='SecondMethod']/*" /> 
    Public Function SecondMethod(A As Integer) As String 
     Return "Hello" 
    End Function 

    ''' <include file="DocFile.xml" path="Doc/member[@name='SecondMethod']/*" /> 
    Public Function SecondMethod(A As Integer, B As String) As String 
     Return "Hello" 
    End Function 

    ''' <include file="DocFile.xml" path="Doc/member[@name='SecondMethod']/*" /> 
    Public Function SecondMethod(A As Integer, B As String, C As Boolean) As String 
     Return "Hello" 
    End Function 

End Class 

だからクラスのためのドキュメントと最初のメソッドは "標準"です。 SecondMethodでは、XMLリンクを提供します。

あなたがここにあなたがあなたのメソッドのドキュメントを置くDocFile.XMLと呼ばれる、XMLファイルを作成する必要がありますので、次の:

<Doc> 
    <member name="SecondMethod"> 
    <summary> 
     This is my second method 
    </summary> 
    <param name="A">a</param> 
    <param name="B">b</param> 
    <param name="C">c</param> 
    <returns>A string containing "Hello"</returns> 
    <remarks></remarks> 
    </member> 
</Doc> 

そして、あなたはそれを一緒にコンパイルして文書を作成する(ここで私が使用しましたSandCastle)、それは以下を生成します。

enter image description here

そして、それぞれの方法について:

enter image description here

enter image description here

TLDR

  • XMLファイルに一度のドキュメントを作成し、この文書にメソッドをリンクすることが可能です。
  • あなたは(ここで私は2010のExpressのVSを使用)
  • ケースは、Visual Studio
  • 敏感である一つの定義に多くの方法をリンクさせることができ、この1には本当に参考になっていない、それはあなたがやっていることのないアイデアを持っていません。コンパイルすると、プロジェクトのインテリセンスでそれを見ることができなくなります。別のソリューションを作成してライブラリを参照すると、そのライブラリが表示されます。