Merge pull request #59 from danilolutz/docs/add-docs

docs: add documentations

Author: danilolutz

.github/workflows/publish-docs.yml

@@ -0,0 +1,42 @@
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+  
+jobs:
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    
+    - name: Dotnet Setup
+      uses: actions/setup-dotnet@v3
+      with:
+        dotnet-version: 8.x
+
+    - run: dotnet tool update -g docfx
+    - run: docfx docs/docfx.json
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: 'docs/_site'
+    
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -555,3 +555,6 @@ coverage.json
 coverage.cobertura.xml
 
 # End of https://www.gitignore.io/api/aspnetcore,visualstudio,visualstudiocode,openframeworks+visualstudio
+
+docs/_site
+docs/api

CoreZipCode/Interfaces/PostCodeBaseService.cs

@@ -4,19 +4,16 @@
 
 namespace CoreZipCode.Interfaces
 {
-    /// <inheritdoc />
     /// <summary>
     /// Postcode base service abstract class.
     /// </summary>
     public abstract class PostcodeBaseService : ApiHandler
     {
-        /// <inheritdoc />
         /// <summary>
         /// postalcode base service protected constructor.
         /// </summary>
         protected PostcodeBaseService() { }
 
-        /// <inheritdoc />
         /// <summary>
         /// postalcode base service protected constructor.
         /// </summary>

CoreZipCode/Interfaces/ZipCodeBaseService.cs

@@ -5,19 +5,16 @@
 
 namespace CoreZipCode.Interfaces
 {
-    /// <inheritdoc />
     /// <summary>
     /// Zip code base service abstract class
     /// </summary>
     public abstract class ZipCodeBaseService : ApiHandler
     {
-        /// <inheritdoc />
         /// <summary>
         /// Zip Code Base Service protected constructor.
         /// </summary>
         protected ZipCodeBaseService() { }
 
-        /// <inheritdoc />
         /// <summary>
         /// Zip Code Base Service protected constructor.
         /// </summary>

CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeIn.cs

@@ -3,6 +3,13 @@
 
 namespace CoreZipCode.Services.Postcode.PostalpincodeInApi
 {
+    /// <summary>
+    /// Provides access to the Postalpincode.in API for retrieving postal code information.
+    /// </summary>
+    /// <remarks>This class extends <see cref="PostcodeBaseService"/> to implement API-specific behavior for
+    /// Postalpincode.in. Use this class to construct requests and obtain data related to Indian postal pincodes.
+    /// Instances can be initialized with an <see cref="HttpClient"/> to customize HTTP request handling. 
+    /// For more information about the Postal Pin Code API, see http://www.postalpincode.in/.</remarks>
     public class PostalpincodeIn : PostcodeBaseService
     {
         public PostalpincodeIn() { }

CoreZipCode/Services/Postcode/PostalpincodeInApi/PostalpincodeInModel.cs

@@ -4,6 +4,13 @@
 
 namespace CoreZipCode.Services.Postcode.PostalpincodeInApi
 {
+    /// <summary>
+    /// Represents the response model for postal pincode queries, containing status information, a message, and a
+    /// collection of post office details.  
+    /// </summary>
+    /// <remarks>This class is typically used to deserialize responses from postal pincode APIs. The
+    /// properties correspond to the expected fields in the API response, allowing access to the status, message, and
+    /// associated post office data.</remarks>
     [Serializable]
     public class PostalpincodeInModel
     {
@@ -17,6 +24,14 @@ public class PostalpincodeInModel
         public List<PostOffice> PostOffice { get; set; }
     }
 
+    /// <summary>
+    /// Represents a postal office location and its associated details, including name, branch type, delivery status,
+    /// and geographic information.
+    /// </summary>
+    /// <remarks>This class is typically used to model information about a post office for address validation,
+    /// postal lookup, or geographic categorization scenarios. All properties are read-write and correspond to standard
+    /// attributes found in postal systems. Instances of this class can be serialized for data exchange or storage
+    /// purposes.</remarks>
     [Serializable]
     public class PostOffice
     {

CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIo.cs

@@ -3,6 +3,13 @@
 
 namespace CoreZipCode.Services.Postcode.PostcodesIoApi
 {
+    /// <summary>
+    /// Provides access to postcode lookup services using the Postcodes.io API.
+    /// </summary>
+    /// <remarks>This class extends <see cref="PostcodeBaseService"/>. Use this class to construct requests for postcode 
+    /// information via the postcodes.io endpoint. Inherit from this class to extend or customize postcode-related operations.
+    /// This class is intended for use with UK postcodes and relies on an HTTP client for making API requests. For more 
+    /// information about the Postcodes API, see https://postcodes.io.</remarks>
     public class PostcodesIo : PostcodeBaseService
     {
         public PostcodesIo() { }

CoreZipCode/Services/Postcode/PostcodesIoApi/PostcodesIoModel.cs

@@ -4,6 +4,12 @@
 
 namespace CoreZipCode.Services.Postcode.PostcodesIoApi
 {
+    /// <summary>
+    /// Represents the response model for the Postcodes.io API, containing the status code and a collection of postcode
+    /// results.
+    /// </summary>
+    /// <remarks>This class is typically used to deserialize JSON responses from the Postcodes.io service. The
+    /// structure matches the standard response format returned by the API for postcode queries.</remarks>
     [Serializable]
     public class PostcodesIoModel
     {
@@ -14,6 +20,15 @@ public class PostcodesIoModel
         public List<Result> Result { get; set; }
     }
 
+    /// <summary>
+    /// Represents detailed information about a UK postcode, including geographic, administrative, and electoral data as
+    /// returned by postcode lookup services.  
+    /// </summary>
+    /// <remarks>This class provides structured access to various attributes associated with a postcode, such
+    /// as location coordinates, administrative regions, and health authorities. It is typically used to deserialize
+    /// responses from postcode APIs and may contain null or default values for properties where data is unavailable.
+    /// Thread safety is not guaranteed; if multiple threads access an instance concurrently, external synchronization
+    /// is required.</remarks>
     [Serializable]
     public class Result
     {
@@ -90,6 +105,14 @@ public class Result
         public Codes Codes { get; set; }
     }
 
+    /// <summary>
+    /// Represents a collection of administrative and geographic codes associated with a location, such as district,
+    /// county, ward, parish, and constituency identifiers. 
+    /// </summary>
+    /// <remarks>This class is typically used to provide standardized codes for various administrative
+    /// divisions in the United Kingdom. The codes correspond to specific government or statistical regions and can be
+    /// used for data integration, analysis, or mapping purposes. All properties are optional and may be null if the
+    /// corresponding code is not available.</remarks>
     [Serializable]
     public class Codes
     {

CoreZipCode/Services/ZipCode/SmartyApi/Smarty.cs

@@ -5,6 +5,14 @@
 
 namespace CoreZipCode.Services.ZipCode.SmartyApi
 {
+    /// <summary>
+    /// Provides access to Smarty ZIP code and street address lookup services using authenticated API requests.
+    /// </summary>
+    /// <remarks>Use this class to construct authenticated requests to the Smarty US ZIP code and
+    /// street address APIs. The class requires valid authentication credentials, which are used to authorize each
+    /// request. Inherit from <see cref="ZipCodeBaseService"/> to enable integration with other ZIP code service implementations. This
+    /// class is not thread-safe; create a separate instance for each concurrent operation if needed. For more information about the Smarty API, see
+    /// https://www.smarty.com/.</remarks>
     public class Smarty : ZipCodeBaseService
     {
         private const string ZipCodeSizeErrorMessage = "Invalid ZipCode Size";

CoreZipCode/Services/ZipCode/SmartyApi/SmartyException.cs

@@ -2,6 +2,12 @@
 
 namespace CoreZipCode.Services.ZipCode.SmartyApi
 {
+    /// <summary>
+    /// Represents errors that occur during Smarty operations.  
+    /// </summary>
+    /// <remarks>Use this exception to indicate failures specific to Smarty functionality. This exception is
+    /// typically thrown when an operation cannot be completed due to invalid input, configuration issues, or other
+    /// conditions unique to Smarty. For general exceptions, use the base <see cref="Exception"/> class.</remarks>
     public class SmartyException : Exception
     {
         public SmartyException(string message) : base(message)