lablup / lablup/mlxcel

docs: source comments reference docs/model_tests.md and docs/testing.md, which do not exist

Open
#1,658 0 comments 0 reactions 0 assignees View on GitHub
priority:low status:ready type:docs
Dominant language
Rust
Stars
467
Forks
54
Avg merge
4h 25m
Merged PRs (30d)
310

Description

## Summary

Six source references point readers at `docs/model_tests.md` or `docs/testing.md`, but neither file exists anywhere in the tree. These are dead documentation pointers. One of them lives inside a user-facing assertion message rather than a comment, so it needs slightly more care.

## Background

There is direct precedent for treating a dead `docs/` pointer as a bug. Issue #26 was the same class of defect (a dead `docs/model_implementations.md` pointer), and a regression test was added for it at `src/main_tests.rs:250-260`. That test is the model for how the project already guards against this.

## Proposed Solution

For each reference, decide per file whether the target doc was moved (repoint to its real location) or deleted (drop the pointer). This is a comment-only change except for the assertion-message case, which must keep a coherent user-facing message after the edit. Consider extending the existing `src/main_tests.rs` guard to also cover `docs/model_tests.md` and `docs/testing.md` so future dead pointers are caught.

## Implementation Notes

References to `docs/model_tests.md` (absent):

- `Cargo.toml:54`
- `src/bin/speculative_bench.rs:23` and `:731`
- `tests/speculative_parity.rs:1405`
- `tests/prompt_cache_prefill_bench.rs:41`

Reference to `docs/testing.md` (absent):

- `src/tokenizer/mod.rs:2645`

- `tests/speculative_parity.rs:1405` is inside an assertion message ("see docs/model_tests.md::Speculative drafters"), not a bare comment. Edit it so the message still reads correctly when the assertion fires.
- The existing regression guard at `src/main_tests.rs:250-260` (added for #26) shows the established pattern for asserting that referenced docs exist.

## Acceptance Criteria

- [ ] No source comment or message references a `docs/*.md` path that does not exist
- [ ] The `tests/speculative_parity.rs:1405` assertion message still reads correctly after the edit
- [ ] Optionally, the `src/main_tests.rs` guard is extended to cover the newly fixed paths

---

## Original Suggestion

### Title: docs: six source comments reference docs/model_tests.md and docs/testing.md, which do not exist

Six source comments point readers at `docs/model_tests.md` or `docs/testing.md`; neither file exists anywhere in the tree. There is direct precedent for treating this as a bug: issue #26 was exactly this class (a dead `docs/model_implementations.md` pointer), and `src/main_tests.rs:250-260` is the regression test that was added for it.

## Evidence

References to `docs/model_tests.md` (absent):

- `Cargo.toml:54`
- `src/bin/speculative_bench.rs:23` and `:731`
- `tests/speculative_parity.rs:1405`
- `tests/prompt_cache_prefill_bench.rs:41`

Reference to `docs/testing.md` (absent):

- `src/tokenizer/mod.rs:2645`

## Suggested fix

Comment-only edits: either restore/point at the real location of the testing documentation or drop the pointers.

**Maintainer input needed before starting:** per file, state whether the referenced doc was moved (and where) or deleted — a newcomer cannot infer that from the tree.

## Acceptance criteria

- [ ] No source comment references a `docs/*.md` path that does not exist
- [ ] The `tests/speculative_parity.rs:1405` case is handled carefully — it is inside a user-facing assertion message, not just a comment

Contributor guide

Open the contributing guide

Research direction

Inspect the six references listed in Cargo.toml, src/bin/speculative_bench.rs, tests/speculative_parity.rs, tests/prompt_cache_prefill_bench.rs, and src/tokenizer/mod.rs, then read the existing guard at src/main_tests.rs:250-260. Confirm with a maintainer whether each target was moved or deleted, update the pointers and assertion message accordingly, and run the relevant tests to verify no dead docs paths remain.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, testing
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.