As is common, I have a series of overloaded methods that all funnel into a single "master" method. Each of the overloads accepts a different combination of parameters and then passes those values on to the "master" along with some "default" values for anything that wasn't included in the overloaded version. I'm attempting to create the XML documentation for these methods, and I would like to indicate in some obvious way what these default values are.
Is there a particular XML tag that can be used by this form of documentation to identify default values that will be passed on to another method? I'd ideally like to see something in IntelliSense that displays something like Default: <parametername> value <defaultvalue>
, although that may be a bit much to ask for within the standard behavior of the XML documentation features.
If there's no "special" XML tag to use for something like that, I suppose I'll simply need to come up with some appropriate verbiage in the <summary>
or <remarks>
section. Something to the effect of "This will use the default value of <defaultvalue> for <parametername>..."
. I just think it would look better if there were a way to identify these defaults along with the other parameters.
Obviously, this is not a critical need. I'm simply curious at this point and would like to know if I've just overlooked something. Here is a sample of the code in question. I've cut out the actual operational code in the master method as it's irrelevant to this question, but I'll point you to it if anyone needs/wants it.
''' <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
Whenever it comes to properties, its a no brainer. My suggestion would be to extend the value tag to something along these lines:
''' <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
However, when it comes to methods (which is what you originally asked), then I'd go with your gut and include it in the remarks tag or returns.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With