Improve comments and Swagger annotations across services (#26)

- EmailController: add class summary, full SwaggerResponse/ProducesResponseType
  for 400 and 500, and Description on SwaggerOperation
- ContactController: fix terse "Failed." error message to
  "Could not process subscription."
- FileDownloadController: remove redundant XML <response code> tags from
  the public action doc block; convert private-method /// <summary> to //
  (project convention: no XML doc on internal code)
- CvMatcherService: remove two dead commented-out blocks (old email send
  and BuildEmailBody helper)
- JobTokenService: comment the phone/contact-line regex filter in
  ExtractKeywords
- DocumentClassifier: comment the keyword-frequency scoring approach and
  the confidence formula
- TextChunker: comment the sliding-window step (chunkSize - overlap)
- CvSearchJobTask: comment the GdprConsent = true rationale and the
  BuildCvFileName sanitisation logic
- HtmlJobSearcher: comment GetLeftPart(UriPartial.Path) query-strip dedup

Closes #26

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Apis/email-api/Controllers/EmailController.cs

@@ -5,6 +5,11 @@ using Swashbuckle.AspNetCore.Annotations;
 
 namespace EmailApi.Controllers;
 
+/// <summary>
+/// Internal email relay. Accepts an HTML body fragment from trusted callers
+/// (api, cv-search-job), wraps it in the branded HTML shell, and dispatches
+/// via SMTP. Protected by X-Internal-Api-Key.
+/// </summary>
 [ApiController]
 [Route("api/email")]
 public sealed class EmailController : ControllerBase
@@ -13,9 +18,27 @@ public sealed class EmailController : ControllerBase
 
     public EmailController(SmtpEmailDispatcher dispatcher) => _dispatcher = dispatcher;
 
+    /// <summary>
+    /// Sends an HTML email via SMTP. The supplied body fragment is wrapped in
+    /// the branded HTML shell before dispatch. Attachments are resolved from
+    /// the shared file storage volume using the relative path in
+    /// <see cref="SendEmailRequest.AttachmentPath"/>.
+    /// </summary>
+    /// <param name="request">Email payload: recipients, subject, HTML body fragment, optional attachment path.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>204 No Content on success.</returns>
     [HttpPost("send")]
-    [SwaggerOperation(Summary = "Send an HTML email via SMTP")]
+    [SwaggerOperation(
+        Summary = "Send an HTML email via SMTP",
+        Description = "Wraps the provided HTML body in the branded shell and sends via SMTP. " +
+                      "If AttachmentPath is set, resolves the file from the shared file-storage volume. " +
+                      "Returns 204 on success; 400 when the request body is invalid; 500 on SMTP failure.")]
+    [SwaggerResponse(StatusCodes.Status204NoContent, "Email dispatched successfully")]
+    [SwaggerResponse(StatusCodes.Status400BadRequest, "Request body is missing or invalid")]
+    [SwaggerResponse(StatusCodes.Status500InternalServerError, "SMTP dispatch failed")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status500InternalServerError)]
     public async Task<IActionResult> Send([FromBody] SendEmailRequest request, CancellationToken ct)
     {
         await _dispatcher.SendAsync(request, ct);