vb.net - 是否有 "special"方法可以通过 XML 注释识别 IntelliSense 中方法参数的默认值？

Question

通常，我有一系列重载的方法，它们都汇集到一个单一的“主”方法中。每个重载都接受不同的参数组合，然后将这些值连同一些未包含在重载版本中的任何“默认”值一起传递给“主”。我正在尝试为这些方法创建 XML 文档，并且我想以某种明显的方式指出这些默认值是什么。

这种形式的文档是否可以使用特定的 XML 标记来标识将传递给其他方法的默认值？理想情况下，我希望在 IntelliSense 中看到一些显示类似 的内容。 Default: <parametername> value <defaultvalue> ，尽管这在 XML 文档功能的标准行为中可能有点过分。

如果没有“特殊”的 XML 标记可用于类似的事情，我想我只需要在 <summary> 中提出一些适当的措辞即可。或 <remarks>部分。大意是 "This will use the default value of <defaultvalue> for <parametername>..." .我只是认为如果有一种方法可以识别这些默认值以及其他参数，它会更好看。

显然，这不是关键需求。我只是在这一点上很好奇，想知道我是否刚刚忽略了一些东西。这是有问题的代码示例。我已经删除了主方法中的实际操作代码，因为它与这个问题无关，但是如果有人需要/想要它，我会指向它。

“大师”方法

''' <summary>
''' Merges multiple PDF files into a single PDF file
''' </summary>
''' <param name="PDFFiles">A list of specific PDF files to merge</param>
''' <param name="OutputFileName">The PDF file to create from the merged PDF files</param>
''' <param name="OverwriteExistingPDF">If the specified PDF file already exists, identifies whether or not to overwrite the existing file</param>
''' <param name="SortOrder">Identifies the order in which to add the source PDF files to the output file</param>
''' <returns>A FileInfo object representing the merged PDF if successful. <cref>Nothing</cref> if unsuccessful.</returns>
''' <remarks>Using the <see cref="iTextSharp.text.pdf.PdfCopy"/> (<paramref name="UseSmartMerge"/> = <c>False</c>) may result in larger files, 
''' while using the <see cref="iTextSharp.text.pdf.PdfSmartCopy"/> (<paramref name="UseSmartMerge"/> = <c>True</c>) may result in longer processing times.</remarks>
Public Overloads Function Merge(ByVal PDFFiles As List(Of System.IO.FileInfo), ByVal UseSmartMerge As Boolean, ByVal OutputFileName As String, ByVal OverwriteExistingPDF As Boolean, ByVal SortOrder As PDFMergeSortOrder) As System.IO.FileInfo
    Dim ResultFile As System.IO.FileInfo = Nothing
    ...<merge the files>...
    Return ResultFile
End Function

重载方法

''' <summary>
''' Merges multiple PDF files into a single PDF file
''' </summary>
''' <param name="PDFFiles">A list of specific PDF files to merge</param>
''' <param name="OutputFileName">The PDF file to create from the merged PDF files</param>
''' <param name="OverwriteExistingPDF">If the specified PDF file already exists, identifies whether or not to overwrite the existing file</param>
''' <returns>A FileInfo object representing the merged PDF if successful. <cref>Nothing</cref> if unsuccessful.</returns>
Public Overloads Function Merge(ByVal PDFFiles As List(Of System.IO.FileInfo), ByVal OutputFileName As String, ByVal OverwriteExistingPDF As Boolean) As System.IO.FileInfo
    Return Merge(PDFFiles, False, OutputFileName, False, PDFMergeSortOrder.Original)
End Function

''' <summary>
''' Merges multiple PDF files into a single PDF file
''' </summary>
''' <param name="PDFFiles">A list of specific PDF files to merge</param>
''' <param name="UseSmartMerge">Identifies whether to use a regular <see cref="iTextSharp.text.pdf.PdfCopy"/> or the <see cref="iTextSharp.text.pdf.PdfSmartCopy"/> for merging</param>
''' <param name="OutputFileName">The PDF file to create from the merged PDF files</param>
''' <param name="OverwriteExistingPDF">If the specified PDF file already exists, identifies whether or not to overwrite the existing file</param>
''' <returns>A FileInfo object representing the merged PDF if successful. <cref>Nothing</cref> if unsuccessful.</returns>
''' <remarks>Using the <see cref="iTextSharp.text.pdf.PdfCopy"/> (<paramref name="UseSmartMerge"/> = <c>False</c>) may result in larger files, 
''' while using the <see cref="iTextSharp.text.pdf.PdfSmartCopy"/> (<paramref name="UseSmartMerge"/> = <c>True</c>) may result in longer processing times.</remarks>
Public Overloads Function Merge(ByVal PDFFiles As List(Of System.IO.FileInfo), ByVal UseSmartMerge As Boolean, ByVal OutputFileName As String, ByVal OverwriteExistingPDF As Boolean) As System.IO.FileInfo
    Return Merge(PDFFiles, UseSmartMerge, OutputFileName, False, PDFMergeSortOrder.Original)
End Function

''' <summary>
''' Merges multiple PDF files into a single PDF file
''' </summary>
''' <param name="PDFFiles">A list of specific PDF files to merge</param>
''' <param name="OutputFileName">The PDF file to create from the merged PDF files</param>
''' <param name="SortOrder">Identifies the order in which to add the source PDF files to the output file</param>
''' <returns>A FileInfo object representing the merged PDF if successful. <cref>Nothing</cref> if unsuccessful.</returns>
Public Overloads Function Merge(ByVal PDFFiles As List(Of System.IO.FileInfo), ByVal OutputFileName As String, ByVal SortOrder As PDFMergeSortOrder) As System.IO.FileInfo
    Return Merge(PDFFiles, False, OutputFileName, False, SortOrder)
End Function

''' <summary>
''' Merges multiple PDF files into a single PDF file
''' </summary>
''' <param name="PDFFiles">A list of specific PDF files to merge</param>
''' <param name="UseSmartMerge">Identifies whether to use a regular <see cref="iTextSharp.text.pdf.PdfCopy"/> or the <see cref="iTextSharp.text.pdf.PdfSmartCopy"/> for merging</param>
''' <param name="OutputFileName">The PDF file to create from the merged PDF files</param>
''' <param name="SortOrder">Identifies the order in which to add the source PDF files to the output file</param>
''' <returns>A FileInfo object representing the merged PDF if successful. <cref>Nothing</cref> if unsuccessful.</returns>
''' <remarks>Using the <see cref="iTextSharp.text.pdf.PdfCopy"/> (<paramref name="UseSmartMerge"/> = <c>False</c>) may result in larger files, 
''' while using the <see cref="iTextSharp.text.pdf.PdfSmartCopy"/> (<paramref name="UseSmartMerge"/> = <c>True</c>) may result in longer processing times.</remarks>
Public Overloads Function Merge(ByVal PDFFiles As List(Of System.IO.FileInfo), ByVal UseSmartMerge As Boolean, ByVal OutputFileName As String, ByVal SortOrder As PDFMergeSortOrder) As System.IO.FileInfo
    Return Merge(PDFFiles, UseSmartMerge, OutputFileName, False, SortOrder)
End Function
#End Region

Answer 1

每当谈到属性时，它都是毫无意义的。我的建议是延长 value沿着这些路线标记一些东西:

''' <summary>Returns the number of times Counter was called.</summary>
''' <value>Default: 0</value>
''' <returns><see cref="Integer"/> value based on the number of times Counter was called.</returns>
Public Property Counter As Integer

但是，当涉及到方法(这是您最初要求的)时，我会按照您的直觉将其包含在 remarks 中。标签或 returns .