Improve comments and Swagger docs across services #27

2026-05-28T06:07:59Z

gelu commented

2026-05-28 06:07:59 +00:00

What

Code-quality pass: Swagger annotations, inline comments on non-obvious logic, dead code removal, style consistency.

Why

Several services lacked comments on complex logic, had dead-code blocks, or inconsistent Swagger annotation styles leaving the OpenAPI spec incomplete.

Changes

Controllers:

email-api/EmailController: added class summary, full SwaggerResponse/ProducesResponseType for 400 and 500
api/ContactController: fixed terse 'Failed.' error message on Subscribe
api/FileDownloadController: removed redundant XML response tags; converted private XML summary to line comments per project convention

Services:

CvMatcherService: removed two dead-code comment blocks
JobTokenService: added comment on the regex filter in ExtractKeywords
DocumentClassifier: added comments on the keyword-frequency heuristic and confidence formula
TextChunker: added comment on the sliding-window step
CvSearchJobTask: added comment on GdprConsent = true rationale and BuildCvFileName sanitisation
HtmlJobSearcher: added comment on GetLeftPart(UriPartial.Path) deduplication

Testing

dotnet build myAi.sln: 0 errors, 0 warnings
Pure documentation/cleanup, no logic changes

Risk Assessment

Breaking changes? No
Performance impact? None
Closes Improve comments and Swagger documentation across services (#26)

## What Code-quality pass: Swagger annotations, inline comments on non-obvious logic, dead code removal, style consistency. ## Why Several services lacked comments on complex logic, had dead-code blocks, or inconsistent Swagger annotation styles leaving the OpenAPI spec incomplete. ## Changes Controllers: - email-api/EmailController: added class summary, full SwaggerResponse/ProducesResponseType for 400 and 500 - api/ContactController: fixed terse 'Failed.' error message on Subscribe - api/FileDownloadController: removed redundant XML response tags; converted private XML summary to line comments per project convention Services: - CvMatcherService: removed two dead-code comment blocks - JobTokenService: added comment on the regex filter in ExtractKeywords - DocumentClassifier: added comments on the keyword-frequency heuristic and confidence formula - TextChunker: added comment on the sliding-window step - CvSearchJobTask: added comment on GdprConsent = true rationale and BuildCvFileName sanitisation - HtmlJobSearcher: added comment on GetLeftPart(UriPartial.Path) deduplication ## Testing - dotnet build myAi.sln: 0 errors, 0 warnings - Pure documentation/cleanup, no logic changes ## Risk Assessment - Breaking changes? No - Performance impact? None - Closes #26

gelu added 1 commit 2026-05-28 06:07:59 +00:00

Improve comments and Swagger annotations across services (#26 ) 4ee4a59b5e

- 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>

gelu added 1 commit 2026-05-28 06:17:48 +00:00

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

- 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>

claude approved these changes 2026-05-28 06:26:28 +00:00

gelu merged commit 2e1efc598b into main

2026-05-28 06:26:57 +00:00

gelu referenced this pull request

2026-05-28 06:27:06 +00:00

Improve comments and Swagger documentation across services #26

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: AI/myAi#27