fix(android): KDoc nested-comment trap from /api/* literal

Kotlin (unlike Java) supports nested block comments. The doc-comment
on LibraryApi contained the string `/api/*` and `/api/home`-style
paths, which the lexer parsed as opening nested comments:

  /**
   * Retrofit interface for the server's native /api/* library surface.  ← lexer: nested /* opens
   ...
   */                                                                    ← closes the nested one
  // outer comment now unclosed; "Unclosed comment" reported at EOF

This compile error is what caused all the "ModuleProcessingStep was
unable to process NetworkModule because LibraryApi could not be
resolved" failures over the last four commits — KSP runs before
compileDebugKotlin and reports the downstream symptom (unresolvable
symbol) before the actual source-level error gets to print.

Rewrote the doc-comment to use `/api/...` and to wrap concrete paths
in backticks; no `/*` substring remains.

The "repos construct their Retrofit interface from shared Retrofit"
pattern from the previous commit stays; it's a sound pattern arrived
at via the wrong reasoning, but defensible on its own merits (fewer
Hilt bindings, locality of reference, easier test override).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-22 21:41:37 -04:00
parent 02175b193b
commit d08c937f3b
@@ -8,20 +8,20 @@ import retrofit2.http.Path
import retrofit2.http.Query
/**
* Retrofit interface for the server's native /api/* library surface.
* Retrofit interface for the server's native `/api/...` library surface.
* Mirrors `flutter_client/lib/api/endpoints/library.dart` 1:1.
*
* Notes on shapes:
* - GET /api/artists/{id} returns ArtistDetailWire (ArtistRef fields
* + embedded "albums" array)
* - GET /api/artists/{id}/tracks returns a bare JSON array, not an
* - `GET /api/artists/{id}` returns ArtistDetailWire (ArtistRef fields
* plus embedded "albums" array)
* - `GET /api/artists/{id}/tracks` returns a bare JSON array, not an
* enveloped object — Retrofit's `List<TrackWire>` return type
* handles that.
* - GET /api/albums/{id} returns AlbumDetailWire (AlbumRef fields
* + embedded "tracks" array)
* - GET /api/library/shuffle returns a bare JSON array.
* - `GET /api/albums/{id}` returns AlbumDetailWire (AlbumRef fields
* plus embedded "tracks" array)
* - `GET /api/library/shuffle` returns a bare JSON array.
*
* Home endpoints (/api/home, /api/home/index) live in a separate
* Home endpoints (`/api/home`, `/api/home/index`) live in a separate
* `HomeApi` because they have their own wire types (HomePayload,
* HomeIndex) that are larger and only used by the Home screen.
*/