[Docs] The five classes that carry the project have no doc comment at all #624

New issue

Closed

opened 2026-07-22 16:21:53 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:21:53 +00:00

Owner

Found in the pre-publication architecture review.

Evidence: lib/services/markdown_service.dart:42 — class MarkdownService, 2,322 lines, zero lines of dartdoc; line 41 is blank. The same for lib/services/file_service.dart (FileService, 2,879 lines, 0), lib/state/tabs_provider.dart (TabsNotifier, 2,403, 0), lib/state/settings_provider.dart (SettingsNotifier, 1,331, 0), lib/state/deck_provider.dart (DeckNotifier, 1,307, 0). PrivacyScanner and SlideQualityAnalyzer have one line each.

Measured across lib/ excluding l10n: 118 public types with no dartdoc — 28 in models, 23 in services, 21 in state, 41 in widgets.

Why this matters now: this is precisely the ten-minute test. Someone wanting to check the premise of OciDeck — that Markdown is the source of truth — opens markdown_service.dart and finds a 2,322-line class with not one sentence about its contract. That same file has excellent commentary (lines 37-38 explain why the regexes are hoisted), so the impression is not "sloppy" but "there is something here you will have to work out yourself" — which is worse, because it is untrue.

Proposal: six to nine doc comments of three to five lines each on the classes above: what is the contract, what is the invariant, what should you not expect from it. No refactor, no renaming. For the remaining 118, a counter in check_conventions.dart with the current figure as a baseline, so the number can only fall.

Found in the pre-publication architecture review. **Evidence:** `lib/services/markdown_service.dart:42` — `class MarkdownService`, 2,322 lines, **zero** lines of dartdoc; line 41 is blank. The same for `lib/services/file_service.dart` (`FileService`, 2,879 lines, 0), `lib/state/tabs_provider.dart` (`TabsNotifier`, 2,403, 0), `lib/state/settings_provider.dart` (`SettingsNotifier`, 1,331, 0), `lib/state/deck_provider.dart` (`DeckNotifier`, 1,307, 0). `PrivacyScanner` and `SlideQualityAnalyzer` have one line each. Measured across `lib/` excluding l10n: **118 public types with no dartdoc** — 28 in models, 23 in services, 21 in state, 41 in widgets. **Why this matters now:** this is precisely the ten-minute test. Someone wanting to check the premise of OciDeck — that Markdown is the source of truth — opens `markdown_service.dart` and finds a 2,322-line class with not one sentence about its contract. That same file *has* excellent commentary (lines 37-38 explain why the regexes are hoisted), so the impression is not "sloppy" but "there is something here you will have to work out yourself" — which is worse, because it is untrue. **Proposal:** six to nine doc comments of three to five lines each on the classes above: what is the contract, what is the invariant, what should you *not* expect from it. No refactor, no renaming. For the remaining 118, a counter in `check_conventions.dart` with the current figure as a baseline, so the number can only fall.

brenno added the

docs

label

2026-07-22 16:21:53 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:10 +00:00

docs(code): geef de vijf dragende klassen een contract, en meet de mutatietest (#624 #616)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs(code): geef de vijf dragende klassen een contract, en meet de mutatietest (#624 #616)

brenno referenced this issue

2026-07-22 17:14:10 +00:00