Add XML doc to all service interfaces and implementations (#26)

- Update CLAUDE.md: replace incorrect 'no XML doc on internal code' rule
  with the correct convention (XML doc on all public methods and
  non-trivial private/protected helpers)
- Restore /// <summary> on FileDownloadController private helpers
  (HandleRangeRequest, StreamRangeAsync)
- Add full XML doc to all service contracts:
  ICaptchaVerifier, IEmailSender, ICvMatcherService, IJobTextExtractor,
  IJobTokenService, IDocumentClassifier, IRagService, ITextChunker,
  ITextExtractor, IEmailTemplateService, ITemplateService
- Add /// <summary> and /// <inheritdoc /> to all concrete service classes
  and their methods: RecaptchaVerifier, EmailApiEmailSender,
  SmtpEmailDispatcher, CvMatcherService, JobTextExtractor, JobTokenService,
  RagService, DocumentClassifier, TextChunker, TextExtractor,
  HtmlJobSearcher, CvSearchEmailSender, CvSearchJobTask,
  EmailTemplateService, DbTemplateService

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-28 09:17:42 +03:00
parent 4ee4a59b5e
commit 16bb195cb5
28 changed files with 436 additions and 6 deletions
@@ -4,6 +4,9 @@ using Rag.Models;
namespace Api.Services;
/// <summary>
/// Classifies documents by type using a keyword-frequency heuristic and extracts a title from the text.
/// </summary>
public sealed class DocumentClassifier : IDocumentClassifier
{
private static readonly HashSet<string> KnownTypes = new(StringComparer.OrdinalIgnoreCase)
@@ -11,6 +14,7 @@ public sealed class DocumentClassifier : IDocumentClassifier
"cv", "job", "article", "contract", "invoice", "product", "documentation", "unknown"
};
/// <inheritdoc />
public Task<DocumentClassification> ClassifyAsync(string text, string? providedType, string? providedTitle, CancellationToken ct)
{
if (!string.IsNullOrWhiteSpace(providedType))
@@ -51,14 +55,20 @@ public sealed class DocumentClassifier : IDocumentClassifier
});
}
/// <summary>Counts how many of the given <paramref name="terms"/> appear in the lower-cased text.</summary>
private static int Count(string lower, params string[] terms) => terms.Count(term => lower.Contains(term));
/// <summary>Lowercases and replaces non-alphanumeric characters with hyphens to produce a safe type slug.</summary>
private static string NormalizeType(string value)
{
var cleaned = Regex.Replace(value.Trim().ToLowerInvariant(), "[^a-z0-9_-]", "-");
return string.IsNullOrWhiteSpace(cleaned) ? "unknown" : cleaned;
}
/// <summary>
/// Returns <paramref name="providedTitle"/> when available; otherwise extracts the first sentence-like
/// fragment from the text, or falls back to a generic "{type} document" label.
/// </summary>
private static string BuildTitle(string? providedTitle, string text, string documentType)
{
if (!string.IsNullOrWhiteSpace(providedTitle)) return providedTitle.Trim();