AI/myAi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Improve comments and Swagger documentation across services #26

New Issue
Closed
opened 2026-05-28 06:04:44 +00:00 by gelu · 1 comment
gelu commented 2026-05-28 06:04:44 +00:00
Owner
Copy Link
Copy Source

What

Code-quality pass: add or fix inline comments for non-obvious logic, fix Swagger annotations on EmailController, remove dead commented-out code, and normalise XML doc comment usage.

Why

Several services have either no comments on complex logic, outdated dead code blocks that clutter reading, or inconsistent Swagger annotation style that makes the OpenAPI spec incomplete.

Scope

Controller fixes

  • email-api/EmailController - missing class summary, missing SwaggerResponse/ProducesResponseType for 400/500, missing Description on SwaggerOperation
  • api/ContactController - Subscribe action returns Error = "Failed." (too terse); fix to "Could not process subscription."
  • api/FileDownloadController - redundant XML response code tags alongside SwaggerResponse attributes; private helper methods use XML summary comments (violates project convention)

Service fixes

  • cv-matcher-api/CvMatcherService - remove two large dead-code comment blocks (old email/body helpers)
  • cv-matcher-api/JobTokenService - ExtractKeywords regex filter is non-obvious; add a brief comment
  • rag-api/DocumentClassifier - keyword-scoring approach and confidence formula are undocumented; add comments
  • rag-api/TextChunker - sliding-window step (chunkSize - overlap) is non-obvious; add a comment
  • cv-search-job/CvSearchJobTask - BuildCvFileName sanitisation and hardcoded GdprConsent = true deserve brief comments
  • cv-search-job/HtmlJobSearcher - GetLeftPart(UriPartial.Path) for query-strip dedup has no comment

Success criteria

  • dotnet build myAi.sln passes with 0 errors, 0 warnings
  • email-api Swagger UI shows 400 and 500 responses for POST /api/email/send
  • No dead commented-out code remains in CvMatcherService
  • No XML doc summary on private/internal methods

Time tracking

Started: 2026-05-28 09:04 UTC

## What Code-quality pass: add or fix inline comments for non-obvious logic, fix Swagger annotations on `EmailController`, remove dead commented-out code, and normalise XML doc comment usage. ## Why Several services have either no comments on complex logic, outdated dead code blocks that clutter reading, or inconsistent Swagger annotation style that makes the OpenAPI spec incomplete. ## Scope ### Controller fixes - **email-api/EmailController** - missing class summary, missing SwaggerResponse/ProducesResponseType for 400/500, missing Description on SwaggerOperation - **api/ContactController** - Subscribe action returns Error = "Failed." (too terse); fix to "Could not process subscription." - **api/FileDownloadController** - redundant XML response code tags alongside SwaggerResponse attributes; private helper methods use XML summary comments (violates project convention) ### Service fixes - **cv-matcher-api/CvMatcherService** - remove two large dead-code comment blocks (old email/body helpers) - **cv-matcher-api/JobTokenService** - ExtractKeywords regex filter is non-obvious; add a brief comment - **rag-api/DocumentClassifier** - keyword-scoring approach and confidence formula are undocumented; add comments - **rag-api/TextChunker** - sliding-window step (chunkSize - overlap) is non-obvious; add a comment - **cv-search-job/CvSearchJobTask** - BuildCvFileName sanitisation and hardcoded GdprConsent = true deserve brief comments - **cv-search-job/HtmlJobSearcher** - GetLeftPart(UriPartial.Path) for query-strip dedup has no comment ## Success criteria - dotnet build myAi.sln passes with 0 errors, 0 warnings - email-api Swagger UI shows 400 and 500 responses for POST /api/email/send - No dead commented-out code remains in CvMatcherService - No XML doc summary on private/internal methods ## Time tracking Started: 2026-05-28 09:04 UTC
gelu closed this issue 2026-05-28 06:26:57 +00:00
gelu commented 2026-05-28 06:27:06 +00:00
Author
Owner
Copy Link
Copy Source

Completed: 2026-05-28 09:27 UTC — merged via PR #27.

Duration: ~1 hour

Completed: 2026-05-28 09:27 UTC — merged via PR #27. Duration: ~1 hour
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claude gelu
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: AI/myAi#26
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?