compact comments

Author: arielvino

src/pages/components/map-related/MapIndex.tsx

@@ -7,8 +7,6 @@ export function MapIndex({
   subtitle,
 }: {
   lineColor: string
-  /** The marker as it appears on the map. An element rather than a URL, so a glyph drawn inline
-   * (the bearing arrow) can be painted by the same stylesheet as its counterpart on the map. */
   icon: ReactNode
   title: string
   subtitle?: ReactNode

src/pages/components/map-related/MapLayers/MapIndexLayer.stories.tsx

@@ -11,8 +11,8 @@ const meta = {
   component: MapIndexLayer,
   parameters: { layout: 'centered' },
   // Every legend rule in map.scss is nested under `.map-info` and its `.map-legend` slot, so
-  // mounted bare the legend gets no grid and glyphs at their intrinsic size. Reproduce MapShell's
-  // two levels; the wrapper needs a size because `.map-legend` is absolutely positioned in it.
+  // mounted bare the legend gets no grid and glyphs at their intrinsic size. The outer size is
+  // needed because `.map-legend` is absolutely positioned within it.
   decorators: [
     (Story) => (
       <div className="map-info" style={{ width: 340, height: 210 }}>

src/pages/components/map-related/MapLayers/MapIndexLayer.tsx

@@ -59,8 +59,7 @@ export function MapIndexLayer({ showPlannedRoute, positionGroups = [] }: MapInde
         <MapIndex
           key={idx}
           lineColor={group.color}
-          // A mid-ramp arrow stands for the whole family here; MapSpeedIndex below spells the
-          // bands out.
+          // A mid-ramp arrow stands for the whole family; MapSpeedIndex below spells the bands out.
           icon={<VehicleBearingGlyph band={SPEED_BANDS[SPEED_BANDS.length - 2]} />}
           title={t('actualRoute')}
           subtitle={vehicleSubtitle(group, t)}

src/pages/components/map-related/MapLayers/MapRouteLayer.tsx

@@ -21,15 +21,7 @@ interface MapRouteLayerProps {
   navigateMarkers: (groupIndex: number, id: number, marker: Layer) => void
 }
 
-/**
- * A ping the vehicle reported moving becomes an arrow along its bearing, grown and filled in by
- * how fast; one it reported standing at (velocity exactly 0) becomes the compass badge, which
- * still faces the way the bus did. Both read the same `velocity` the tooltip prints, so the
- * shape can never contradict the number behind it — and both carry the stacking order that
- * keeps the small glyphs on top of the big ones.
- *
- * (`Point.color` holds that velocity, not a colour — see `toPoint`.)
- */
+/** `Point.color` holds the ping's velocity, not a colour — see `toPoint`. */
 function pingMarker({ bearing, color: velocity }: Point) {
   // Only the standing badge can say "heading unknown" (it drops its needle); a moving ping has
   // to point somewhere, and `toPoint` has already defaulted a missing SIRI bearing to 0 anyway.
@@ -69,8 +61,7 @@ export function MapRouteLayer({
             />
             {group.positions.map((pos, i) => {
               const markerKey = `${groupIndex}-${i}`
-              // The ride is bookended: its operator's logo where it started, a chequered disc
-              // where it was last seen. A one-ping ride keeps the logo — it never got to finish.
+              // A one-ping ride keeps the operator's logo — it never got to finish.
               const { icon, zIndexOffset } =
                 i === 0
                   ? {

src/pages/components/map-related/MapSpeedIndex.tsx

@@ -7,10 +7,6 @@ import {
   VehicleStandingGlyph,
 } from './vehicleBearingGlyph'
 
-/**
- * Key to the ping markers' speed ramp: the compass badge for a bus reported standing, then an
- * arrow per band, growing as it goes faster and red across the slow half.
- */
 export function MapSpeedIndex() {
   const { t } = useTranslation()
 

src/pages/components/map-related/map-types.ts

@@ -1,8 +1,8 @@
 import type { SiriVehicleLocationWithRelatedPydanticModel } from '@hasadna/open-bus-api-client'
 import { BusStop } from 'src/model/busStop'
 
-/** One per concurrent ride on the map, cycled. Deliberately no red — that belongs to the ping
- * speed ramp (`.ping-arrow--slow`), and red arrows over a red line read as neither. */
+/** Deliberately no red — that belongs to the ping speed ramp (`.ping-arrow--slow`), and red
+ * arrows over a red line read as neither. */
 export const ROUTE_COLORS = ['#f97316', '#3b82f6', '#22c55e', '#a855f7', '#0891b2']
 
 export interface Point {

src/pages/components/map-related/mapMarkers.test.ts

@@ -86,7 +86,7 @@ describe('rideEndMarker', () => {
   it('clips the chequer to the badge, so it runs to the edge without escaping the disc', () => {
     const clipId = /<clipPath id="([^"]+)">/.exec(html)![1]
     expect(html).toContain(`clip-path="url(#${clipId})"`)
-    // the clip circle is the badge, a hair smaller so the rim survives on top of the cells
+    // a hair smaller than the disc, so the rim survives on top of the cells
     const clipR = Number(/<clipPath[^>]*><circle[^>]*r="([\d.]+)"/.exec(html)![1])
     const discR = Number(/<circle class="ping-badge"[^>]*r="([\d.]+)"/.exec(html)![1])
     expect(clipR).toBeLessThan(discR)

src/pages/components/map-related/mapMarkers.ts

@@ -1,7 +1,6 @@
 /**
- * Every Leaflet icon and line colour the map draws with, and nothing that renders.
- *
- * Apart from `MapContent` because the layers it renders need these too, which made
+ * Every Leaflet icon and line colour the map draws with, and nothing that renders. Apart from
+ * `MapContent` because the layers it renders need these too, which made
  * `MapContent → MapLayers/* → MapContent` an import cycle — `madge --circular` fails CI on it.
  * Keep this module free of component imports.
  */
@@ -26,17 +25,14 @@ const getIcon = (
   })
 }
 
-/** Carried by both vehicle-ping shapes (standing ring and bearing arrow) so a ping can be
- * selected without knowing which of the two it got. */
+/** Carried by every ping shape, so a ping can be selected without knowing which one it got. */
 export const vehiclePingMarkerClass = 'vehicle-ping-marker'
 
-/** Leaflet's box for a ping glyph, in px. It stays the same across every speed band and the
- * standing glyph too, so the click target doesn't shrink with the speed and the icon keeps
- * centring on its ping without per-band anchor arithmetic. */
+/** One box for every speed band and the standing glyph alike, so the click target doesn't shrink
+ * with the speed and the icon centres on its ping without per-band anchor arithmetic. */
 const PING_ICON_PX = 28
 
-/** The ride-end badge gets the ride-start circle's 30px instead, so a ride's two ends are the
- * same size — and its chequer gets the pixels it needs to read as one. */
+/** The ride-start circle's 30px in `map.scss`, so a ride's two ends are the same size. */
 const RIDE_END_ICON_PX = 30
 
 const pingIconOptions = (className: string, html: string, px: number = PING_ICON_PX) => ({
@@ -51,14 +47,8 @@ const standingMarkers = new Map<string, DivIcon>()
 /** Onto 0-359, the convention SVG `rotate()` shares with SIRI (0 = north, clockwise). */
 const normalizeBearing = (bearing: number) => ((Math.round(bearing) % 360) + 360) % 360
 
-/**
- * Arrow marker pointing where the vehicle was heading, from the ping's SIRI bearing
- * (0 = north, clockwise — the same convention SVG `rotate()` uses), grown by how fast it was
- * travelling and reddened if that was slow (see {@link speedBand}).
- *
- * Instances are cached per whole degree and band, so a ride's hundreds of pings share at most
- * 360 × 4 icons and re-renders reuse the same object.
- */
+/** Cached per whole degree and band, so a ride's hundreds of pings share at most 360 × 6 icons
+ * and re-renders hand Leaflet the same object back. */
 export const vehicleBearingMarker = (bearing: number, speedKmh: number): DivIcon => {
   const deg = normalizeBearing(bearing)
   const band = speedBand(speedKmh)
@@ -71,13 +61,6 @@ export const vehicleBearingMarker = (bearing: number, speedKmh: number): DivIcon
   return icon
 }
 
-/**
- * Marker for a ping the vehicle reported standing at: the ride-start marker's white disc, with a
- * compass needle inside showing the way it was facing. Nothing else on the map is a disc this
- * size, so the one exact reading the arrows can never carry — velocity 0 — keeps its own shape.
- *
- * A bearing of `undefined` drops the needle rather than inventing a heading.
- */
 export const vehicleStandingMarker = (bearing?: number): DivIcon => {
   const deg = bearing === undefined ? undefined : normalizeBearing(bearing)
   const key = `${deg}`
@@ -89,10 +72,6 @@ export const vehicleStandingMarker = (bearing?: number): DivIcon => {
   return icon
 }
 
-/**
- * Marker for the ride's last ping: a chequered disc, the finish line to the operator's logo at
- * the start. One per ride, so it is built once rather than cached per bearing.
- */
 export const rideEndMarker = new DivIcon(
   pingIconOptions('vehicle-ride-end-marker', rideEndSvgMarkup(), RIDE_END_ICON_PX),
 )

src/pages/components/map-related/vehicleBearingGlyph.test.ts

@@ -13,17 +13,9 @@ import {
   standingSvgMarkup,
 } from './vehicleBearingGlyph'
 
-/**
- * The speed ramp the ping arrows are drawn from. Bands are a deliberate quantisation, not a
- * rounding artefact: they keep the marker cache to a few hundred icons, and they give the
- * legend something finite to spell out.
- */
-
 const TOP = SPEED_BAND_MAX.length
 
 describe('isStanding', () => {
-  // The whole point of the standing glyph is that it means one exact reading, so that the
-  // marker can never say "stopped" over a tooltip that says 3 km/h.
   it('is the exact zero the vehicle reported, with no tolerance band under it', () => {
     expect(isStanding(0)).toBe(true)
     expect(isStanding(1)).toBe(false)
@@ -46,9 +38,8 @@ describe('speedBand', () => {
 })
 
 describe('speedBandLabel', () => {
-  // Spelled out rather than rebuilt from SPEED_BAND_MAX: a change to the ramp then has to be
-  // read back off the legend it produces, and the standing glyph's 0 has to still meet the
-  // first band's 1 with no km/h left unaccounted for between any two rungs.
+  // Spelled out rather than rebuilt from SPEED_BAND_MAX, so a change to the ramp has to be read
+  // back off the legend it produces — with no km/h unaccounted for between any two rungs.
   it('spells each band out as its km/h range, the last one open-ended', () => {
     expect(STANDING_LABEL).toBe('0')
     expect(SPEED_BANDS.map(speedBandLabel)).toEqual([
@@ -101,13 +92,12 @@ describe('standingSvgMarkup', () => {
 })
 
 describe('marker stacking', () => {
-  // Zoomed out, a ride is a handful of pixels: whatever sits lowest here is what gets buried.
   it('puts the ride bookends over every ping, and the smaller pings over the bigger ones', () => {
     const bands = SPEED_BANDS.map(bearingZIndex)
 
     expect(BOOKEND_Z_INDEX).toBeGreaterThan(STANDING_Z_INDEX)
     expect(STANDING_Z_INDEX).toBeGreaterThan(Math.max(...bands))
-    // strictly descending: band 0 is the smallest arrow and stays on top of the rest
+    // strictly descending: band 0 is the smallest arrow and stays on top
     expect(bands).toEqual([...bands].sort((a, b) => b - a))
     expect(new Set(bands).size).toBe(bands.length)
   })