#3 Adding XML docs to public methods.

Author: kevbite

src/Kevsoft.PDFtk/IDataField.cs

@@ -1,15 +1,53 @@
 namespace Kevsoft.PDFtk
 {
+    /// <summary>
+    /// Statistics of a single data field within the PDF. 
+    /// </summary>
     public interface IDataField
     {
+        /// <summary>
+        /// The field value.
+        /// </summary>
         string? FieldValue { get; }
+        
+        /// <summary>
+        /// The default field value.
+        /// </summary>
         string? FieldValueDefault { get; }
+        
+        /// <summary>
+        /// The field type.
+        /// </summary>
         string? FieldType { get; }
+        
+        /// <summary>
+        /// The field name.
+        /// </summary>
         string? FieldName { get; }
+        
+        /// <summary>
+        /// The field alternative description.
+        /// </summary>
         string? FieldNameAlt { get; }
+        
+        /// <summary>
+        /// The field flags.
+        /// </summary>
         string? FieldFlags { get; }
+        
+        /// <summary>
+        /// The field justification.
+        /// </summary>
         string? FieldJustification { get; }
+        
+        /// <summary>
+        /// The field possible values.
+        /// </summary>
         string[] FieldStateOption { get; }
+        
+        /// <summary>
+        /// The field maximum length.
+        /// </summary>
         string? FieldMaxLength { get; }
     }
 }

src/Kevsoft.PDFtk/IPDFtk.cs

@@ -4,40 +4,184 @@
 
 namespace Kevsoft.PDFtk
 {
+    /// <summary>
+    /// The main <c>IPDFtk</c> interface.
+    /// Contains all methods for performing the PDFtk functions.
+    /// </summary>
     public interface IPDFtk
     {
-        Task<IPDFtkResult<int?>> GetNumberOfPagesAsync(byte[] pdfFileBytes);
-        Task<IPDFtkResult<int?>> GetNumberOfPagesAsync(Stream pdfFileStream);
+        /// <summary>
+        /// Return the number of pages for a given PDF.
+        /// </summary>
+        /// <param name="pdfFile">A byte array of the PDF file input.</param>
+        /// <returns>A result with the number of pages.</returns>
+        /// See <see cref="GetNumberOfPagesAsync(Stream)"/> to use a PDF input as a stream or <see cref="GetNumberOfPagesAsync(string)"/> to use a PDF file path. 
+        Task<IPDFtkResult<int?>> GetNumberOfPagesAsync(byte[] pdfFile);
+
+        /// <summary>
+        /// Return the number of pages for a given PDF.
+        /// </summary>
+        /// <param name="pdfFile">A stream containing the PDF file input.</param>
+        /// <returns>A result with the number of pages.</returns>
+        /// See <see cref="GetNumberOfPagesAsync(byte[])"/> to use a PDF input as a byte array or <see cref="GetNumberOfPagesAsync(string)"/> to use a PDF file path. 
+        Task<IPDFtkResult<int?>> GetNumberOfPagesAsync(Stream pdfFile);
+ 
+        /// <summary>
+        /// Return the number of pages for a given PDF.
+        /// </summary>
+        /// <param name="filePath">The PDF file path.</param>
+        /// <returns>A result with the number of pages.</returns>
+        /// See <see cref="GetNumberOfPagesAsync(byte[])"/> to use a PDF input as a byte array. 
         Task<IPDFtkResult<int?>> GetNumberOfPagesAsync(string filePath);
-        Task<IPDFtkResult<byte[]>> GetPagesAsync(byte[] pdfFileBytes, params int[] pages);
-        Task<IPDFtkResult<byte[]>> GetPagesAsync(Stream pdfFileBytes, params int[] pages);
-        Task<IPDFtkResult<byte[]>> GetPagesAsync(string inputFile, params int[] pages);
-        Task<IPDFtkResult<IDataField[]>> GetDataFieldsAsync(byte[] pdfFileBytes);
+        
+        /// <summary>
+        /// Concatenate a list of pages into one single file and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="pdfFile">A byte array of the PDF file input.</param>
+        /// <param name="pages">The pages to concatenate.</param>
+        /// <returns>A result with the PDF as a byte array with the concatenated pages.</returns>
+        Task<IPDFtkResult<byte[]>> GetPagesAsync(byte[] pdfFile, params int[] pages);
+        
+        /// <summary>
+        /// Concatenate a list of pages into one single file and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="pdfFile">A stream of the PDF file input.</param>
+        /// <param name="pages">The pages to concatenate.</param>
+        /// <returns>A result with the PDF as a byte array with the concatenated pages.</returns>
+        Task<IPDFtkResult<byte[]>> GetPagesAsync(Stream pdfFile, params int[] pages);
+        
+        /// <summary>
+        /// Concatenate a list of pages into one single file and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="filePath">The PDF file path.</param>
+        /// <param name="pages">The pages to concatenate.</param>
+        /// <returns>A result with the PDF as a byte array with the concatenated pages.</returns>
+        Task<IPDFtkResult<byte[]>> GetPagesAsync(string filePath, params int[] pages);
+        
+        /// <summary>
+        /// Reads the PDF and returns the form field statistics.
+        /// </summary>
+        /// <param name="pdfFile">A byte array of the PDF file input.</param>
+        /// <returns>A result with the form field statistics</returns>
+        Task<IPDFtkResult<IDataField[]>> GetDataFieldsAsync(byte[] pdfFile);
+        
+        /// <summary>
+        /// Reads the PDF and returns the form field statistics.
+        /// </summary>
+        /// <param name="pdfFile">A stream of the PDF file input.</param>
+        /// <returns>A result with the form field statistics</returns>
         Task<IPDFtkResult<IDataField[]>> GetDataFieldsAsync(Stream pdfFile);
+        
+        /// <summary>
+        /// Reads the PDF and returns the form field statistics.
+        /// </summary>
+        /// <param name="filePath">The PDF file path.</param>
+        /// <returns>A result with the form field statistics</returns>  
         Task<IPDFtkResult<IDataField[]>> GetDataFieldsAsync(string filePath);
+        
+        /// <summary>
+        /// Merges multiple PDFs into one single PDF and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="pdfFiles">An enumeration of bytes of the PDF files to merge.</param>
+        /// <returns>A result with the PDF as a byte array of the merged PDFs.</returns>
         Task<IPDFtkResult<byte[]>> ConcatAsync(IEnumerable<byte[]> pdfFiles);
-        Task<IPDFtkResult<byte[]>> ConcatAsync(IEnumerable<Stream> pdfStreams);
+        
+        /// <summary>
+        /// Merges multiple PDFs into one single PDF and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="pdfFiles">An enumeration of streams of the PDF files to merge.</param>
+        /// <returns>A result with the PDF as a byte array of the merged PDFs.</returns>
+        Task<IPDFtkResult<byte[]>> ConcatAsync(IEnumerable<Stream> pdfFiles);
+        
+        /// <summary>
+        /// Merges multiple PDFs into one single PDF and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="filePaths">An enumeration of the PDF file paths to merge.</param>
+        /// <returns>A result with the PDF as a byte array of the merged PDFs.</returns>
         Task<IPDFtkResult<byte[]>> ConcatAsync(IEnumerable<string> filePaths);
+        
+        /// <summary>
+        /// Splits a single PDF in many pages and return an enumeration of bytes representing each page a s single PDF.
+        /// </summary>
+        /// <param name="pdfFile">A byte array of the PDF file input.</param>
+        /// <returns>A result with an enumeration of byte arrays.</returns>
         Task<IPDFtkResult<IEnumerable<byte[]>>> SplitAsync(byte[] pdfFile);
-        Task<IPDFtkResult<IEnumerable<byte[]>>> SplitAsync(Stream stream);
+        
+        /// <summary>
+        /// Splits a single PDF in many pages and return an enumeration of bytes representing each page a s single PDF.
+        /// </summary>
+        /// <param name="pdfFile">A stream of the PDF file input.</param>
+        /// <returns>A result with an enumeration of byte arrays.</returns>
+        Task<IPDFtkResult<IEnumerable<byte[]>>> SplitAsync(Stream pdfFile);
+        
+        /// <summary>
+        /// Splits a single PDF in many pages and return an enumeration of bytes representing each page a s single PDF.
+        /// </summary>
+        /// <param name="filePath">The PDF file path.</param>
+        /// <returns>A result with an enumeration of byte arrays.</returns>
         Task<IPDFtkResult<IEnumerable<byte[]>>> SplitAsync(string filePath);
+        
+        /// <summary>
+        /// Applies a stamp to a PDF file.
+        /// </summary>
+        /// <param name="pdfFile">A byte array of the PDF file input.</param>
+        /// <param name="stampPdfFile">A byte array of the PDF stamp to apply.</param>
+        /// <returns>A result with the stamped PDF file.</returns>
         Task<IPDFtkResult<byte[]>> StampAsync(byte[] pdfFile, byte[] stampPdfFile);
-        Task<IPDFtkResult<byte[]>> StampAsync(Stream pdfFileStream, Stream stampPdfFileStream);
+        
+        /// <summary>
+        /// Applies a stamp to a PDF file.
+        /// </summary>
+        /// <param name="pdfFile">A stream of the PDF file input.</param>
+        /// <param name="stampPdfFile">A stream of the PDF stamp to apply.</param>
+        /// <returns>A result with the stamped PDF file.</returns>
+        Task<IPDFtkResult<byte[]>> StampAsync(Stream pdfFile, Stream stampPdfFile);
+        
+        /// <summary>
+        /// Applies a stamp to a PDF file.
+        /// </summary>
+        /// <param name="pdfFilePath">A PDF file path.</param>
+        /// <param name="stampPdfFilePath">A PDF stamp file path.</param>
+        /// <returns>A result with the stamped PDF file.</returns>
         Task<IPDFtkResult<byte[]>> StampAsync(string pdfFilePath, string stampPdfFilePath);
 
+        /// <summary>
+        /// Fill a PDF form with given data and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="pdfFile">A byte array of the PDF file input.</param>
+        /// <param name="fieldData">A key value pair of form field name to value.</param>
+        /// <param name="flatten">If the final PDF should be flattened.</param>
+        /// <param name="dropXfa">If the XFA data should be omitted from final PDF.</param>
+        /// <returns>A result with the PDF form filled as a byte array.</returns>
         Task<IPDFtkResult<byte[]>> FillFormAsync(byte[] pdfFile,
             IReadOnlyDictionary<string, string> fieldData,
-            bool flatten,
-            bool dropXfa);
+            bool flatten = true,
+            bool dropXfa = false);
 
-        Task<IPDFtkResult<byte[]>> FillFormAsync(Stream stream,
+        /// <summary>
+        /// Fill a PDF form with given data and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="pdfFile">A stream of the PDF file input.</param>
+        /// <param name="fieldData">A key value pair of form field name to value.</param>
+        /// <param name="flatten">If the final PDF should be flattened.</param>
+        /// <param name="dropXfa">If the XFA data should be omitted from final PDF.</param>
+        /// <returns>A result with the PDF form filled as a byte array.</returns>
+        Task<IPDFtkResult<byte[]>> FillFormAsync(Stream pdfFile,
             IReadOnlyDictionary<string, string> fieldData,
-            bool flatten,
-            bool dropXfa);
+            bool flatten = true,
+            bool dropXfa = false);
 
+        /// <summary>
+        /// Fill a PDF form with given data and returns the output PDF as a byte array.
+        /// </summary>
+        /// <param name="pdfFilePath">A PDF file path.</param>
+        /// <param name="fieldData">A key value pair of form field name to value.</param>
+        /// <param name="flatten">If the final PDF should be flattened.</param>
+        /// <param name="dropXfa">If the XFA data should be omitted from final PDF.</param>
+        /// <returns>A result with the PDF form filled as a byte array.</returns>
         Task<IPDFtkResult<byte[]>> FillFormAsync(string pdfFilePath,
             IReadOnlyDictionary<string, string> fieldData,
-            bool flatten,
-            bool dropXfa);
+            bool flatten = true,
+            bool dropXfa = false);
     }
 }

src/Kevsoft.PDFtk/IPDFtkResult.cs

@@ -1,11 +1,30 @@
 namespace Kevsoft.PDFtk
 {
+    /// <summary>
+    /// The result of a PDFtk execution.
+    /// </summary>
+    /// <typeparam name="TResult">The enclosed result type.</typeparam>
     public interface IPDFtkResult<out TResult>
     {
+        /// <summary>
+        /// The standard output captured when PDFtk was executed.
+        /// </summary>
         string StandardOutput  { get; }
+        /// <summary>
+        /// The standard error captured when PDFtk was executed.
+        /// </summary>
         string StandardError { get; }
+        /// <summary>
+        /// The result of the execution.
+        /// </summary>
         TResult Result { get; }
+        /// <summary>
+        /// The exit code of the execution of PDFtk.
+        /// </summary>
         int ExitCode { get; }
+        /// <summary>
+        /// Success flag of the execution of PDFtk.
+        /// </summary>
         bool Success { get; }
     }
 }

src/Kevsoft.PDFtk/Kevsoft.PDFtk.csproj

@@ -7,8 +7,9 @@
   <PropertyGroup>
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
-
+  
   <PropertyGroup>
     <Title>Kevsoft.PDFtk</Title>
     <AssemblyName>Kevsoft.PDFtk</AssemblyName>
@@ -24,6 +25,10 @@
     <Copyright>Copyright © Kevsoft 2021</Copyright>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
+  </PropertyGroup>
+  
   <PropertyGroup>
     <PackageTags>PDFtk;pdf</PackageTags>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>