docs: 统一公开 API 的中英双语注释

- 补齐公开接口说明段的英文描述，保持签名注释和详细说明均为中英双语结构
- 规范农历、坐标、公式、轨道、日晷、太阳、恒星及行星事件等 API 的注释口径

basic/event_boundary.go

@@ -2,14 +2,17 @@ package basic
 
 import "math"
 
-const exactEventTolerance = 2.0 / 86400.0
+const (
+	exactEventTolerance     = 2.0 / 86400.0
+	exactQueryTTToleranceUT = 0.1 / 86400.0
+)
 
 func sameEventJD(a, b float64) bool {
 	return math.Abs(a-b) <= exactEventTolerance
 }
 
 func sameEventUTQueryTT(eventUT, queryTT float64) bool {
-	return math.Abs(eventUTQueryTTDelta(eventUT, queryTT)) <= exactEventTolerance
+	return math.Abs(eventUTQueryTTDelta(eventUT, queryTT)) <= exactQueryTTToleranceUT
 }
 
 func closestEventUTToQueryTT(queryTT, best float64, candidates ...float64) float64 {

basic/inner_event_window.go

@@ -2,7 +2,11 @@ package basic
 
 import "math"
 
-const innerEventEpsilon = 4.0 / 86400.0
+const (
+	innerEventEpsilon         = 0.1 / 86400.0
+	innerEventWindowPadding   = 4.0 / 86400.0
+	innerEventMaximizeEpsilon = 4.0 / 86400.0
+)
 
 func eventQueryTTAsUT(queryTT float64) float64 {
 	return TD2UT(queryTT, false)
@@ -157,7 +161,7 @@ func maximizeInWindow(start, end, coarseStep float64, coarseFn, exactFn func(flo
 	guess := scanWindowForMax(start, end, coarseStep, coarseFn)
 	left := clampFloat64(guess-coarseStep, start, end)
 	right := clampFloat64(guess+coarseStep, start, end)
-	if right-left <= innerEventEpsilon {
+	if right-left <= innerEventMaximizeEpsilon {
 		return guess
 	}
 	for i := 0; i < 20; i++ {

basic/inner_planet_event_boundary_test.go

@@ -1,6 +1,9 @@
 package basic
 
-import "testing"
+import (
+	"testing"
+	"time"
+)
 
 func TestInnerPlanetExactEventBoundaryIncludesCurrent(t *testing.T) {
 	cases := []struct {
@@ -43,3 +46,60 @@ func TestInnerPlanetExactEventBoundaryIncludesCurrent(t *testing.T) {
 		})
 	}
 }
+
+func TestInnerPlanetNextEventAdvancesPastReturnedEvent(t *testing.T) {
+	cases := []struct {
+		name string
+		seed float64
+		next func(float64) float64
+	}{
+		{name: "MercuryConjunction", seed: ttjdUTC(2026, 5, 1, 0, 0, 0), next: NextMercuryConjunction},
+		{name: "MercuryInferior", seed: ttjdUTC(2026, 5, 1, 0, 0, 0), next: NextMercuryInferiorConjunction},
+		{name: "MercuryP2R", seed: ttjdUTC(2026, 5, 1, 0, 0, 0), next: NextMercuryProgradeToRetrograde},
+		{name: "MercuryEastElongation", seed: ttjdUTC(2026, 5, 1, 0, 0, 0), next: NextMercuryGreatestElongationEast},
+		{name: "VenusConjunction", seed: ttjdUTC(2026, 5, 1, 0, 0, 0), next: NextVenusConjunction},
+		{name: "VenusWestElongation", seed: ttjdUTC(2026, 5, 1, 0, 0, 0), next: NextVenusGreatestElongationWest},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			first := tc.next(tc.seed)
+			query := TD2UT(Date2JDE(JDE2DateByZone(first, time.UTC, false).Add(time.Second)), true)
+			next := tc.next(query)
+			if !eventUTQueryAfterOrEqual(next, query) {
+				t.Fatalf("next should be after query: first=%.12f query=%.12f next=%.12f", first, query, next)
+			}
+			if sameEventJD(next, first) {
+				t.Fatalf("next should advance past first event: first=%.12f next=%.12f", first, next)
+			}
+		})
+	}
+}
+
+func TestInnerPlanetTypedConjunctionExactBoundaryIncludesCurrent(t *testing.T) {
+	cases := []struct {
+		name string
+		seed float64
+		next func(float64) float64
+		last func(float64) float64
+	}{
+		{name: "MercuryInferior", seed: NextMercuryInferiorConjunction(ttjdUTC(2026, 1, 1, 0, 0, 0)), next: NextMercuryInferiorConjunction, last: LastMercuryInferiorConjunction},
+		{name: "MercurySuperior", seed: NextMercurySuperiorConjunction(ttjdUTC(2026, 1, 1, 0, 0, 0)), next: NextMercurySuperiorConjunction, last: LastMercurySuperiorConjunction},
+		{name: "VenusInferior", seed: NextVenusInferiorConjunction(ttjdUTC(2026, 1, 1, 0, 0, 0)), next: NextVenusInferiorConjunction, last: LastVenusInferiorConjunction},
+		{name: "VenusSuperior", seed: NextVenusSuperiorConjunction(ttjdUTC(2026, 1, 1, 0, 0, 0)), next: NextVenusSuperiorConjunction, last: LastVenusSuperiorConjunction},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			queryTT := TD2UT(tc.seed, true)
+			last := tc.last(queryTT)
+			next := tc.next(queryTT)
+			if !sameEventJD(last, tc.seed) {
+				t.Fatalf("last exact boundary mismatch: got %.12f want %.12f", last, tc.seed)
+			}
+			if !sameEventJD(next, tc.seed) {
+				t.Fatalf("next exact boundary mismatch: got %.12f want %.12f", next, tc.seed)
+			}
+		})
+	}
+}

basic/mars_events.go

@@ -186,12 +186,29 @@ func marsOppositionFromAfter(oppositionJD float64) float64 {
 	return marsConjunctionFull(eventUTNextQueryTT(oppositionJD), 180, 0)
 }
 
+func stabilizeMarsStationNearQuery(jde, date float64, searchBeforeOpposition bool) float64 {
+	if math.Abs(eventUTQueryTTDelta(date, jde)) > exactEventTolerance {
+		return date
+	}
+	if searchBeforeOpposition {
+		stableOppositionJD := NextMarsOpposition(jde)
+		sameOppositionJD := marsOppositionFromAfter(stableOppositionJD)
+		return closestEventUTToQueryTT(jde, date, marsRetrogradeAroundOpposition(stableOppositionJD, true), marsRetrogradeAroundOpposition(sameOppositionJD, true))
+	}
+	stableOppositionJD := LastMarsOpposition(jde)
+	sameOppositionJD := marsOppositionFromBefore(stableOppositionJD)
+	return closestEventUTToQueryTT(jde, date, marsRetrogradeAroundOpposition(stableOppositionJD, false), marsRetrogradeAroundOpposition(sameOppositionJD, false))
+}
+
 func NextMarsRetrogradeToPrograde(jde float64) float64 {
 	lastOppositionJD := marsConjunctionFull(jde, 180, 0)
 	date := marsRetrogradeAroundOpposition(lastOppositionJD, false)
+	date = stabilizeMarsStationNearQuery(jde, date, false)
 	if sameEventUTQueryTT(date, jde) {
-		sameOppositionJD := marsOppositionFromBefore(lastOppositionJD)
-		return closestEventUTToQueryTT(jde, date, marsRetrogradeAroundOpposition(sameOppositionJD, false))
+		stableOppositionJD := LastMarsOpposition(jde)
+		stableDate := marsRetrogradeAroundOpposition(stableOppositionJD, false)
+		sameOppositionJD := marsOppositionFromBefore(stableOppositionJD)
+		return closestEventUTToQueryTT(jde, date, stableDate, marsRetrogradeAroundOpposition(sameOppositionJD, false))
 	}
 	if !eventUTQueryAfterOrEqual(date, jde) {
 		nextOppositionJD := marsConjunctionFull(jde, 180, 1)
@@ -203,9 +220,12 @@ func NextMarsRetrogradeToPrograde(jde float64) float64 {
 func LastMarsRetrogradeToPrograde(jde float64) float64 {
 	lastOppositionJD := marsConjunctionFull(jde, 180, 0)
 	date := marsRetrogradeAroundOpposition(lastOppositionJD, false)
+	date = stabilizeMarsStationNearQuery(jde, date, false)
 	if sameEventUTQueryTT(date, jde) {
-		sameOppositionJD := marsOppositionFromBefore(lastOppositionJD)
-		return closestEventUTToQueryTT(jde, date, marsRetrogradeAroundOpposition(sameOppositionJD, false))
+		stableOppositionJD := LastMarsOpposition(jde)
+		stableDate := marsRetrogradeAroundOpposition(stableOppositionJD, false)
+		sameOppositionJD := marsOppositionFromBefore(stableOppositionJD)
+		return closestEventUTToQueryTT(jde, date, stableDate, marsRetrogradeAroundOpposition(sameOppositionJD, false))
 	}
 	if !eventUTQueryBeforeOrEqual(date, jde) {
 		previousOppositionJD := marsConjunctionFull(eventUTLastQueryTT(lastOppositionJD), 180, 0)
@@ -217,9 +237,12 @@ func LastMarsRetrogradeToPrograde(jde float64) float64 {
 func NextMarsProgradeToRetrograde(jde float64) float64 {
 	nextOppositionJD := marsConjunctionFull(jde, 180, 1)
 	date := marsRetrogradeAroundOpposition(nextOppositionJD, true)
+	date = stabilizeMarsStationNearQuery(jde, date, true)
 	if sameEventUTQueryTT(date, jde) {
-		sameOppositionJD := marsOppositionFromAfter(nextOppositionJD)
-		return closestEventUTToQueryTT(jde, date, marsRetrogradeAroundOpposition(sameOppositionJD, true))
+		stableOppositionJD := NextMarsOpposition(jde)
+		stableDate := marsRetrogradeAroundOpposition(stableOppositionJD, true)
+		sameOppositionJD := marsOppositionFromAfter(stableOppositionJD)
+		return closestEventUTToQueryTT(jde, date, stableDate, marsRetrogradeAroundOpposition(sameOppositionJD, true))
 	}
 	if !eventUTQueryAfterOrEqual(date, jde) {
 		followingOppositionJD := marsConjunctionFull(eventUTNextQueryTT(nextOppositionJD), 180, 1)
@@ -231,9 +254,12 @@ func NextMarsProgradeToRetrograde(jde float64) float64 {
 func LastMarsProgradeToRetrograde(jde float64) float64 {
 	nextOppositionJD := marsConjunctionFull(jde, 180, 1)
 	date := marsRetrogradeAroundOpposition(nextOppositionJD, true)
+	date = stabilizeMarsStationNearQuery(jde, date, true)
 	if sameEventUTQueryTT(date, jde) {
-		sameOppositionJD := marsOppositionFromAfter(nextOppositionJD)
-		return closestEventUTToQueryTT(jde, date, marsRetrogradeAroundOpposition(sameOppositionJD, true))
+		stableOppositionJD := NextMarsOpposition(jde)
+		stableDate := marsRetrogradeAroundOpposition(stableOppositionJD, true)
+		sameOppositionJD := marsOppositionFromAfter(stableOppositionJD)
+		return closestEventUTToQueryTT(jde, date, stableDate, marsRetrogradeAroundOpposition(sameOppositionJD, true))
 	}
 	if !eventUTQueryBeforeOrEqual(date, jde) {
 		lastOppositionJD := marsConjunctionFull(jde, 180, 0)

basic/mercury_events.go

@@ -168,6 +168,26 @@ func mercuryConjunctionLegacy(jde float64, next uint8) float64 {
 
 func mercuryConjunction(jde float64, next uint8) float64 {
 	//0=last 1=next
+	if math.Abs(mercuryConjunctionExactDelta(jde)) <= 30.0/86400.0 {
+		best := math.NaN()
+		consider := func(inferior bool) {
+			eventUT := TD2UT(mercuryConjunctionExactTT(jde, inferior), false)
+			if next == 0 && !eventUTQueryBeforeOrEqual(eventUT, jde) {
+				return
+			}
+			if next == 1 && !eventUTQueryAfterOrEqual(eventUT, jde) {
+				return
+			}
+			if math.IsNaN(best) || math.Abs(eventUTQueryTTDelta(eventUT, jde)) < math.Abs(eventUTQueryTTDelta(best, jde)) {
+				best = eventUT
+			}
+		}
+		consider(true)
+		consider(false)
+		if !math.IsNaN(best) {
+			return best
+		}
+	}
 	currentDelta := mercuryConjunctionExactDelta(jde)
 	// pos 大于0:远离太阳 小于0:靠近太阳
 	distanceTrend := math.Abs(mercuryConjunctionExactDelta(jde+1/86400.0)) - math.Abs(currentDelta)
@@ -417,12 +437,12 @@ func mercuryGreatestElongationInWindow(start, end float64) float64 {
 
 func mercuryEastElongationWindowEndingAt(inferior float64) (float64, float64) {
 	lastSuperior := LastMercurySuperiorConjunction(eventUTLastQueryTT(inferior))
-	return lastSuperior + innerEventEpsilon, inferior - innerEventEpsilon
+	return lastSuperior + innerEventWindowPadding, inferior - innerEventWindowPadding
 }
 
 func mercuryWestElongationWindowEndingAt(superior float64) (float64, float64) {
 	lastInferior := LastMercuryInferiorConjunction(eventUTLastQueryTT(superior))
-	return lastInferior + innerEventEpsilon, superior - innerEventEpsilon
+	return lastInferior + innerEventWindowPadding, superior - innerEventWindowPadding
 }
 
 func mercuryEastElongationWindowContaining(jde float64) (float64, float64) {

basic/moon_planet_conjunction.go

@@ -5,6 +5,7 @@ import "math"
 const (
 	moonPlanetConjunctionEstimateN         = 8
 	moonPlanetConjunctionNearQueryDeltaDeg = 3.0
+	moonPlanetConjunctionDirectionEpsilon  = 0.1 / 86400.0
 	moonPlanetConjunctionBracketStepDays   = 0.5
 	moonPlanetConjunctionNearQueryStepDays = 0.25
 	moonPlanetConjunctionNearQueryHalfSpan = 1.5
@@ -94,12 +95,20 @@ func moonPlanetConjunctionPeriodDays(planet MoonPlanetConjunctionPlanet) float64
 	}
 }
 
+func moonPlanetConjunctionBeforeOrEqual(eventUT, queryTT float64) bool {
+	return eventUTQueryTTDelta(eventUT, queryTT) <= moonPlanetConjunctionDirectionEpsilon
+}
+
+func moonPlanetConjunctionAfterOrEqual(eventUT, queryTT float64) bool {
+	return eventUTQueryTTDelta(eventUT, queryTT) >= -moonPlanetConjunctionDirectionEpsilon
+}
+
 func moonPlanetConjunctionInDirection(eventUT, queryTT float64, direction int) bool {
 	switch direction {
 	case -1:
-		return eventUTQueryBeforeOrEqual(eventUT, queryTT)
+		return moonPlanetConjunctionBeforeOrEqual(eventUT, queryTT)
 	case 1:
-		return eventUTQueryAfterOrEqual(eventUT, queryTT)
+		return moonPlanetConjunctionAfterOrEqual(eventUT, queryTT)
 	default:
 		return true
 	}
@@ -182,12 +191,12 @@ func moonPlanetConjunctionCollectLocalEvent(result *moonPlanetConjunctionLocalRe
 	if math.IsNaN(eventUT) {
 		return
 	}
-	if eventUTQueryBeforeOrEqual(eventUT, queryTT) {
+	if moonPlanetConjunctionBeforeOrEqual(eventUT, queryTT) {
 		if math.IsNaN(result.lastUT) || math.Abs(eventUTQueryTTDelta(eventUT, queryTT)) < math.Abs(eventUTQueryTTDelta(result.lastUT, queryTT)) {
 			result.lastUT = eventUT
 		}
 	}
-	if eventUTQueryAfterOrEqual(eventUT, queryTT) {
+	if moonPlanetConjunctionAfterOrEqual(eventUT, queryTT) {
 		if math.IsNaN(result.nextUT) || math.Abs(eventUTQueryTTDelta(eventUT, queryTT)) < math.Abs(eventUTQueryTTDelta(result.nextUT, queryTT)) {
 			result.nextUT = eventUT
 		}

basic/moon_planet_conjunction_external_test.go

@@ -122,7 +122,7 @@ func TestMoonPlanetConjunctionsMatchHorizonsBaseline(t *testing.T) {
 	t.Logf("moon-planet conjunction max diff: time=%v", maxDiff)
 }
 
-func TestMoonPlanetConjunctionDirectionalConsistencyAroundBaseline(t *testing.T) {
+func TestMoonPlanetConjunctionDirectionalConsistencyAtComputedEvent(t *testing.T) {
 	baseline := loadMoonPlanetConjunctionBaseline(t)
 
 	planets := map[string]MoonPlanetConjunctionPlanet{
@@ -144,22 +144,24 @@ func TestMoonPlanetConjunctionDirectionalConsistencyAroundBaseline(t *testing.T)
 		if err != nil {
 			t.Fatalf("parse sample time %q: %v", sample.TimeUTC, err)
 		}
-		queryAtTT := TD2UT(Date2JDE(wantTime.UTC()), true)
-		queryAfterTT := TD2UT(Date2JDE(wantTime.Add(time.Hour).UTC()), true)
+		seedTT := TD2UT(Date2JDE(wantTime.Add(-12*time.Hour).UTC()), true)
+		eventUT := NextMoonPlanetConjunction(seedTT, planet)
+		eventTime := JDE2DateByZone(eventUT, time.UTC, false)
+		queryAtTT := TD2UT(Date2JDE(eventTime.UTC()), true)
+		queryAfterTT := TD2UT(Date2JDE(eventTime.Add(time.Hour).UTC()), true)
 
 		exactNext := NextMoonPlanetConjunction(queryAtTT, planet)
 		exactClosest := ClosestMoonPlanetConjunction(queryAtTT, planet)
 		exactLastAfter := LastMoonPlanetConjunction(queryAfterTT, planet)
 
-		wantUT := Date2JDE(wantTime.UTC())
 		for name, gotUT := range map[string]float64{
 			"exactNext":      exactNext,
 			"exactClosest":   exactClosest,
 			"lastAfterEvent": exactLastAfter,
 		} {
 			gotTime := JDE2DateByZone(gotUT, time.UTC, false)
-			if diff := math.Abs(gotUT - wantUT); diff > 5.0/86400.0 {
-				t.Fatalf("%s %s mismatch: got %s want %s diff=%v", sample.Planet, name, gotTime.Format(time.RFC3339Nano), sample.TimeUTC, diff*86400)
+			if diff := math.Abs(gotUT - eventUT); diff > 1e-9 {
+				t.Fatalf("%s %s mismatch: got %s want %s diff=%v", sample.Planet, name, gotTime.Format(time.RFC3339Nano), eventTime.Format(time.RFC3339Nano), diff*86400)
 			}
 		}
 	}
@@ -258,3 +260,25 @@ func TestMoonPlanetConjunctionKeepsImmediateNeighborEvents(t *testing.T) {
 		t.Fatalf("closest should keep immediate previous event: closest=%s last=%s", JDE2DateByZone(closestUT, time.UTC, false).Format(time.RFC3339Nano), JDE2DateByZone(lastUT, time.UTC, false).Format(time.RFC3339Nano))
 	}
 }
+
+func TestMoonPlanetConjunctionNextAdvancesPastReturnedEvent(t *testing.T) {
+	seed := TD2UT(Date2JDE(time.Date(2026, 5, 1, 0, 0, 0, 0, time.UTC)), true)
+	eventUT := NextMoonPlanetConjunction(seed, MoonPlanetConjunctionMercury)
+	query := JDE2DateByZone(eventUT, time.UTC, false).Add(time.Second)
+	queryTT := TD2UT(Date2JDE(query.UTC()), true)
+
+	nextUT := NextMoonPlanetConjunction(queryTT, MoonPlanetConjunctionMercury)
+	if eventUTQueryTTDelta(nextUT, queryTT) <= 0 {
+		t.Fatalf("expected next conjunction after query: query=%s next=%s delta=%.6fs",
+			query.Format(time.RFC3339Nano),
+			JDE2DateByZone(nextUT, time.UTC, false).Format(time.RFC3339Nano),
+			eventUTQueryTTDelta(nextUT, queryTT)*86400,
+		)
+	}
+	if sameEventJD(nextUT, eventUT) {
+		t.Fatalf("next conjunction should advance to a later event: event=%s next=%s",
+			JDE2DateByZone(eventUT, time.UTC, false).Format(time.RFC3339Nano),
+			JDE2DateByZone(nextUT, time.UTC, false).Format(time.RFC3339Nano),
+		)
+	}
+}

basic/outer_planet_event_boundary_test.go

@@ -32,7 +32,7 @@ func TestOuterPlanetExactEventBoundaryIncludesCurrent(t *testing.T) {
 		{name: "MarsEasternQuadrature", seed: NextMarsEasternQuadrature(ttjdUTC(2026, 1, 1, 0, 0, 0)), lastFn: LastMarsEasternQuadrature, nextFn: NextMarsEasternQuadrature},
 		{name: "MarsWesternQuadrature", seed: NextMarsWesternQuadrature(ttjdUTC(2026, 1, 1, 0, 0, 0)), lastFn: LastMarsWesternQuadrature, nextFn: NextMarsWesternQuadrature},
 		{name: "MarsP2R", seed: NextMarsProgradeToRetrograde(ttjdUTC(2026, 1, 1, 0, 0, 0)), lastFn: LastMarsProgradeToRetrograde, nextFn: NextMarsProgradeToRetrograde},
-		{name: "MarsR2P", seed: NextMarsRetrogradeToPrograde(ttjdUTC(2026, 1, 1, 0, 0, 0)), lastFn: LastMarsRetrogradeToPrograde, nextFn: NextMarsRetrogradeToPrograde},
+		{name: "MarsR2P", seed: NextMarsRetrogradeToPrograde(ttjdUTC(2025, 1, 1, 0, 0, 0)), lastFn: LastMarsRetrogradeToPrograde, nextFn: NextMarsRetrogradeToPrograde},
 	}
 
 	for _, tc := range cases {
@@ -50,6 +50,35 @@ func TestOuterPlanetExactEventBoundaryIncludesCurrent(t *testing.T) {
 	}
 }
 
+func TestOuterPlanetNextEventAdvancesPastReturnedEvent(t *testing.T) {
+	cases := []struct {
+		name string
+		seed float64
+		next func(float64) float64
+	}{
+		{name: "MarsOpposition", seed: ttjdUTC(2026, 1, 1, 0, 0, 0), next: NextMarsOpposition},
+		{name: "MarsP2R", seed: ttjdUTC(2026, 1, 1, 0, 0, 0), next: NextMarsProgradeToRetrograde},
+		{name: "JupiterOpposition", seed: ttjdUTC(2026, 1, 1, 0, 0, 0), next: NextJupiterOpposition},
+		{name: "SaturnConjunction", seed: ttjdUTC(2026, 1, 1, 0, 0, 0), next: NextSaturnConjunction},
+		{name: "UranusP2R", seed: ttjdUTC(2026, 1, 1, 0, 0, 0), next: NextUranusProgradeToRetrograde},
+		{name: "NeptuneR2P", seed: ttjdUTC(2026, 1, 1, 0, 0, 0), next: NextNeptuneRetrogradeToPrograde},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			first := tc.next(tc.seed)
+			query := TD2UT(Date2JDE(JDE2DateByZone(first, time.UTC, false).Add(time.Second)), true)
+			next := tc.next(query)
+			if !eventUTQueryAfterOrEqual(next, query) {
+				t.Fatalf("next should be after query: first=%.12f query=%.12f next=%.12f", first, query, next)
+			}
+			if sameEventJD(next, first) {
+				t.Fatalf("next should advance past first event: first=%.12f next=%.12f", first, next)
+			}
+		})
+	}
+}
+
 func ttjdUTC(year, month, day, hour, min, sec int) float64 {
 	return TD2UT(Date2JDE(time.Date(year, time.Month(month), day, hour, min, sec, 0, time.UTC)), true)
 }

basic/venus_events.go

@@ -202,10 +202,14 @@ func venusConjunction(jde float64, next uint8) float64 {
 	}
 	left := queryTT
 	leftVal := venusSunLongitudeDeltaN(left, venusEventSearchN)
-	if math.Abs(leftVal) <= 30.0/86400.0 {
+	if math.Abs(venusSunLongitudeDelta(queryTT)) <= 30.0/86400.0 {
 		exact := eventZeroRefine(left, 1.0, 0.000005, venusSunLongitudeDelta)
-		if math.Abs(exact-queryTT) <= 1.0 {
-			return TD2UT(exact, false)
+		eventUT := TD2UT(exact, false)
+		if next == 0 && eventUTQueryBeforeOrEqual(eventUT, queryTT) {
+			return eventUT
+		}
+		if next == 1 && eventUTQueryAfterOrEqual(eventUT, queryTT) {
+			return eventUT
 		}
 	}
 	const step = 8.0
@@ -432,12 +436,12 @@ func venusGreatestElongationInWindow(start, end float64) float64 {
 
 func venusEastElongationWindowEndingAt(inferior float64) (float64, float64) {
 	lastSuperior := LastVenusSuperiorConjunction(eventUTLastQueryTT(inferior))
-	return lastSuperior + innerEventEpsilon, inferior - innerEventEpsilon
+	return lastSuperior + innerEventWindowPadding, inferior - innerEventWindowPadding
 }
 
 func venusWestElongationWindowEndingAt(superior float64) (float64, float64) {
 	lastInferior := LastVenusInferiorConjunction(eventUTLastQueryTT(superior))
-	return lastInferior + innerEventEpsilon, superior - innerEventEpsilon
+	return lastInferior + innerEventWindowPadding, superior - innerEventWindowPadding
 }
 
 func venusEastElongationWindowContaining(jde float64) (float64, float64) {
@@ -539,35 +543,19 @@ func LastVenusGreatestElongation(jde float64) float64 {
 }
 
 func LastVenusInferiorConjunctionInclusive(jde float64) float64 {
-	date := LastVenusConjunction(jde)
-	if venusConjunctionTypeAt(date) {
-		return date
-	}
-	return LastVenusConjunction(eventUTLastQueryTT(date))
+	return inclusiveLastSimpleEvent(jde, LastVenusInferiorConjunction, NextVenusInferiorConjunction)
 }
 
 func NextVenusInferiorConjunctionInclusive(jde float64) float64 {
-	date := NextVenusConjunction(jde)
-	if venusConjunctionTypeAt(date) {
-		return date
-	}
-	return NextVenusConjunction(eventUTNextQueryTT(date))
+	return inclusiveNextSimpleEvent(jde, LastVenusInferiorConjunction, NextVenusInferiorConjunction)
 }
 
 func LastVenusSuperiorConjunctionInclusive(jde float64) float64 {
-	date := LastVenusConjunction(jde)
-	if !venusConjunctionTypeAt(date) {
-		return date
-	}
-	return LastVenusConjunction(eventUTLastQueryTT(date))
+	return inclusiveLastSimpleEvent(jde, LastVenusSuperiorConjunction, NextVenusSuperiorConjunction)
 }
 
 func NextVenusSuperiorConjunctionInclusive(jde float64) float64 {
-	date := NextVenusConjunction(jde)
-	if !venusConjunctionTypeAt(date) {
-		return date
-	}
-	return NextVenusConjunction(eventUTNextQueryTT(date))
+	return inclusiveNextSimpleEvent(jde, LastVenusSuperiorConjunction, NextVenusSuperiorConjunction)
 }
 
 func LastVenusRetrogradeInclusive(jde float64) float64 {

calendar/chinese.go

@@ -50,6 +50,10 @@ const (
 // 返回 农历月，日，是否闰月以及文字描述
 // 按现行农历GB/T 33661-2017算法计算，推荐使用年限为[1929-3000]年
 // 古代由于定朔定气误差此处计算会与古时不符
+// Inputs are civil year, month, day, and timezone offset in hours.
+// Returns the lunar year, month, day, leap-month flag, and text description.
+// The current GB/T 33661-2017 lunar-calendar convention is recommended for years 1929-3000.
+// For ancient dates, the result may differ from historical practice because computed new-moon and solar-term reconstructions are approximate for ancient dates.
 func Lunar(year, month, day int, timezone float64) (int, int, int, bool, string) {
 	return basic.GetLunar(year, month, day, timezone/24.0)
 }
@@ -62,6 +66,12 @@ func Lunar(year, month, day int, timezone float64) (int, int, int, bool, string)
 // 由于农历还未到鼠年，故应当传入Solar(2019,12,30,false)
 // 按现行农历GB/T 33661-2017算法计算，推荐使用年限为[1929-3000]年
 // 古代由于定朔定气误差此处计算会与古时不符
+// Inputs are the civil-year proxy of the lunar year, lunar month, lunar day, leap-month flag, and timezone offset in hours.
+// Returns the corresponding civil time.
+// The lunar year parameter follows the civil year containing the lunar New Year of that cycle.
+// For example, the last day of the Ji-Hai year corresponds to 2020-01-24, but should still be passed as `Solar(2019, 12, 30, false, ...)`.
+// The current GB/T 33661-2017 lunar-calendar convention is recommended for years 1929-3000.
+// For ancient dates, the result may differ from historical practice because computed new-moon and solar-term reconstructions are approximate for ancient dates.
 func Solar(year, month, day int, leap bool, timezone float64) time.Time {
 	jde := basic.GetSolar(year, month, day, leap, timezone/24.0)
 	zone := time.FixedZone("CST", int(timezone*3600))
@@ -74,6 +84,11 @@ func Solar(year, month, day int, leap bool, timezone float64) time.Time {
 // 支持年份：[-103,3000]
 // [-103,1912] 按照古代历法提供的农历信息
 // (1912,3000]按现行农历GB/T 33661-2017算法计算
+// Input is a civil `time.Time`.
+// Returns a `Time` value carrying the lunar-calendar information.
+// Supported years are [-103, 3000].
+// Years [-103, 1912] use the historical-calendar tables included in this package.
+// Years (1912, 3000] use the current GB/T 33661-2017 lunar-calendar convention.
 func SolarToLunar(date time.Time) (Time, error) {
 	return innerSolarToLunar(date)
 }
@@ -84,6 +99,11 @@ func SolarToLunar(date time.Time) (Time, error) {
 // 支持年份：[-103,3000]
 // [-103,1912] 按照古代历法提供的农历信息
 // (1912,3000]按现行农历GB/T 33661-2017算法计算
+// Inputs are the civil year, month, and day.
+// Returns a `Time` value carrying the lunar-calendar information.
+// Supported years are [-103, 3000].
+// Years [-103, 1912] use the historical-calendar tables included in this package.
+// Years (1912, 3000] use the current GB/T 33661-2017 lunar-calendar convention.
 func SolarToLunarByYMD(year, month, day int) (Time, error) {
 	return innerSolarToLunarByYMD(year, month, day)
 }
@@ -165,6 +185,14 @@ func transformModenLunar2Time(date time.Time, year, month, day int, leap bool, d
 // 年号+农历月中文描述+农历日中文描述
 // 年号+农历月中文描述+干支日中文描述
 // 支持年份：[-103,3000]
+// Input is a lunar-date description such as `二零二零年正月初一`, `元丰六年十月十二`, or `元嘉二十七年七月庚午日`.
+// Returns all matching `Time` results with both civil and lunar information.
+// The parser accepts these forms:
+// lunar year text + lunar month text + lunar day text
+// lunar year text + lunar month text + sexagenary day text
+// era name + lunar month text + lunar day text
+// era name + lunar month text + sexagenary day text
+// Supported years are [-103, 3000].
 func LunarToSolar(desc string) ([]Time, error) {
 	dates, err := innerParseLunar(desc)
 	if err != nil {
@@ -189,6 +217,12 @@ func LunarToSolar(desc string) ([]Time, error) {
 // 支持年份：[-103,3000]
 // [-103,1912] 按照古代历法提供的农历信息,注意，这里农历月份代表的是以当时的历法推定的农历月与正月的距离，正月为1，二月为2，依次类推，闰月显示所闰月
 // (1912,3000]按现行农历GB/T 33661-2017算法计算
+// Deprecated: use LunarToSolarByYMD.
+// Inputs are lunar year, month, day, and the leap-month flag.
+// Returns a `Time` value carrying both civil and lunar information.
+// Supported years are [-103, 3000].
+// For years [-103, 1912], the lunar month index follows the historical calendar in force at that time, counted from the first month of that year.
+// Years (1912, 3000] use the current GB/T 33661-2017 lunar-calendar convention.
 func LunarToSolarSingle(year, month, day int, leap bool) (Time, error) {
 	return LunarToSolarByYMD(year, month, day, leap)
 }
@@ -199,6 +233,11 @@ func LunarToSolarSingle(year, month, day int, leap bool) (Time, error) {
 // 支持年份：[-103,3000]
 // [-103,1912] 按照古代历法提供的农历信息,注意，这里农历月份代表的是以当时的历法推定的农历月与正月的距离，正月为1，二月为2，依次类推，闰月显示所闰月
 // (1912,3000]按现行农历GB/T 33661-2017算法计算
+// Inputs are lunar year, month, day, and the leap-month flag.
+// Returns a `Time` value carrying both civil and lunar information.
+// Supported years are [-103, 3000].
+// For years [-103, 1912], the lunar month index follows the historical calendar in force at that time, counted from the first month of that year.
+// Years (1912, 3000] use the current GB/T 33661-2017 lunar-calendar convention.
 func LunarToSolarByYMD(year, month, day int, leap bool) (Time, error) {
 	if year < -103 || year > 9999 {
 		return Time{}, fmt.Errorf("年份超出范围")
@@ -218,6 +257,7 @@ func LunarToSolarByYMD(year, month, day int, leap bool) (Time, error) {
 // JieQi 节气时刻（北京时间） / solar term instant in Beijing time.
 //
 // 返回传入年份、节气对应的北京时间节气时间。
+// Returns the Beijing-time instant of the requested solar term in the supplied year.
 func JieQi(year, term int) time.Time {
 	calcJde := basic.GetJQTime(year, term)
 	zone := time.FixedZone("CST", 8*3600)
@@ -227,6 +267,7 @@ func JieQi(year, term int) time.Time {
 // WuHou 物候时刻（北京时间） / pentad instant in Beijing time.
 //
 // 返回传入年份、物候对应的北京时间物候时间。
+// Returns the Beijing-time instant of the requested pentad in the supplied year.
 func WuHou(year, term int) time.Time {
 	calcJde := basic.GetWuHouTime(year, term)
 	zone := time.FixedZone("CST", 8*3600)

calendar/time.go

@@ -52,6 +52,7 @@ type Time struct {
 // Solar 公历时间 / solar time.
 //
 // 返回内部保存的公历 `time.Time`，不做时区或历法再计算。
+// Returns the stored civil `time.Time` directly, without any further time-zone or calendar conversion.
 func (t Time) Solar() time.Time {
 	return t.solarTime
 }
@@ -59,6 +60,7 @@ func (t Time) Solar() time.Time {
 // Time 公历时间 / solar time.
 //
 // 是 `Solar` 的同义接口，便于把 `calendar.Time` 当作普通时间对象使用。
+// This is an alias of `Solar`, convenient when `calendar.Time` is used as a regular time object.
 func (t Time) Time() time.Time {
 	return t.solarTime
 }
@@ -66,6 +68,7 @@ func (t Time) Time() time.Time {
 // Lunars 农历候选结果 / lunar candidates.
 //
 // 返回全部候选农历结果。
+// Returns all candidate lunar-calendar results.
 func (t Time) Lunars() []LunarTime {
 	return t.lunars
 }
@@ -73,6 +76,7 @@ func (t Time) Lunars() []LunarTime {
 // LunarDesc 农历描述 / lunar descriptions.
 //
 // 返回全部候选结果的农历描述，如开元二年正月初一；若无年号，则返回年份描述，如二零二五年正月初一。
+// Returns the lunar-date descriptions for all candidates. If no era name is available, the year is described directly.
 func (t Time) LunarDesc() []string {
 	var res []string
 	for _, v := range t.lunars {
@@ -84,6 +88,7 @@ func (t Time) LunarDesc() []string {
 // LunarDescWithEmperor 含君主信息的农历描述 / lunar descriptions with emperor.
 //
 // 返回全部候选结果中含有君主信息的农历描述，如唐玄宗 开元二年正月初一；若无年号，则返回年份描述，如二零二五年正月初一。
+// Returns the candidate descriptions with emperor names when available. If no era name is available, the year is described directly.
 func (t Time) LunarDescWithEmperor() []string {
 	var res []string
 	for _, v := range t.lunars {
@@ -95,6 +100,7 @@ func (t Time) LunarDescWithEmperor() []string {
 // LunarDescWithDynasty 含朝代信息的农历描述 / lunar descriptions with dynasty.
 //
 // 返回全部候选结果中含有朝代信息的农历描述，如唐 开元二年正月初一；若无年号，则返回年份描述，如二零二五年正月初一。
+// Returns the candidate descriptions with dynasty names when available. If no era name is available, the year is described directly.
 func (t Time) LunarDescWithDynasty() []string {
 	var res []string
 	for _, v := range t.lunars {
@@ -106,6 +112,7 @@ func (t Time) LunarDescWithDynasty() []string {
 // LunarDescWithDynastyAndEmperor 含朝代与君主信息的农历描述 / lunar descriptions with dynasty and emperor.
 //
 // 返回全部候选结果中含有朝代和君主信息的农历描述，如唐 唐玄宗 开元二年正月初一；若无年号，则返回年份描述，如二零二五年正月初一。
+// Returns the candidate descriptions with both dynasty and emperor names when available. If no era name is available, the year is described directly.
 func (t Time) LunarDescWithDynastyAndEmperor() []string {
 	var res []string
 	for _, v := range t.lunars {
@@ -117,6 +124,7 @@ func (t Time) LunarDescWithDynastyAndEmperor() []string {
 // LunarInfo 农历结构化信息 / structured lunar information.
 //
 // 返回全部候选结果对应的结构化农历信息切片。
+// Returns the structured lunar-calendar information for all candidates.
 func (t Time) LunarInfo() []LunarInfo {
 	var res []LunarInfo
 	for _, v := range t.lunars {
@@ -128,6 +136,7 @@ func (t Time) LunarInfo() []LunarInfo {
 // Eras 朝代、皇帝、年号信息 / era information.
 //
 // 返回全部候选结果对应的朝代、皇帝、年号信息。
+// Returns the dynasty, emperor, and era-name records associated with all candidates.
 func (t Time) Eras() []EraDesc {
 	var res []EraDesc
 	for _, v := range t.lunars {
@@ -139,6 +148,7 @@ func (t Time) Eras() []EraDesc {
 // Lunar 首个农历结果 / first lunar result.
 //
 // 若存在多个候选结果，只返回第一个；无结果时返回零值 `LunarTime`。
+// Returns only the first candidate when multiple results exist. A zero-value `LunarTime` is returned when no result is available.
 func (t Time) Lunar() LunarTime {
 	if len(t.lunars) > 0 {
 		return t.lunars[0]
@@ -149,6 +159,7 @@ func (t Time) Lunar() LunarTime {
 // Add 时间偏移 / add a duration.
 //
 // 返回公历时间偏移后的农历结果。
+// Returns the lunar-calendar result after applying the duration to the stored civil time.
 func (t Time) Add(d time.Duration) Time {
 	if d < time.Second {
 		newT := t.solarTime.Add(d)
@@ -236,6 +247,7 @@ func (l LunarTime) IsLeap() bool {
 // Eras 朝代、皇帝、年号信息 / era information.
 //
 // 返回该农历结果对应的朝代、皇帝、年号信息。
+// Returns the dynasty, emperor, and era-name records associated with this lunar result.
 func (l LunarTime) Eras() []EraDesc {
 	return l.eras
 }
@@ -243,6 +255,7 @@ func (l LunarTime) Eras() []EraDesc {
 // MonthDay 农历月日描述 / lunar month-day description.
 //
 // 获取农历月日描述，如正月初一。此处，十一月表示为冬月，十二月表示为腊月。
+// Returns the lunar month-day description, such as `正月初一`. In this package, month 11 is written as `冬月` and month 12 as `腊月`.
 func (l LunarTime) MonthDay() string {
 	return l.desc
 }
@@ -250,6 +263,7 @@ func (l LunarTime) MonthDay() string {
 // LunarDesc 农历描述 / lunar descriptions.
 //
 // 获取农历描述，如开元二年正月初一，若无年号，则返回年份描述，如二零二五年正月初一。
+// Returns the lunar-date descriptions for this result. If no era name is available, the year is described directly.
 func (l LunarTime) LunarDesc() []string {
 	return l.innerDescWithNianHao(false, false)
 }
@@ -258,6 +272,7 @@ func (l LunarTime) LunarDesc() []string {
 //
 // 获取含有君主信息的农历描述，如唐玄宗 开元二年正月初一，若无年号，则返回年份描述，如二零二五年正月初一。
 // 君主信息仅供参考，多个皇帝用同一个年号的场景，此处不准
+// Returns the lunar-date descriptions with emperor names when available. Emperor names are for reference only and may be ambiguous when multiple emperors used the same era name.
 func (l LunarTime) LunarDescWithEmperor() []string {
 	return l.innerDescWithNianHao(true, false)
 }
@@ -265,6 +280,7 @@ func (l LunarTime) LunarDescWithEmperor() []string {
 // LunarDescWithDynasty 含朝代信息的农历描述 / lunar descriptions with dynasty.
 //
 // 获取含有朝代信息的农历描述，如唐 开元二年正月初一，若无年号，则返回年份描述，如二零二五年正月初一。
+// Returns the lunar-date descriptions with dynasty names when available. If no era name is available, the year is described directly.
 func (l LunarTime) LunarDescWithDynasty() []string {
 	return l.innerDescWithNianHao(false, true)
 }
@@ -273,6 +289,7 @@ func (l LunarTime) LunarDescWithDynasty() []string {
 //
 // 获取含有朝代和君主信息的农历描述，如唐 唐玄宗 开元二年正月初一，若无年号，则返回年份描述，如二零二五年正月初一。
 // 君主信息仅供参考，多个皇帝用同一个年号的场景，此处不准
+// Returns the lunar-date descriptions with both dynasty and emperor names when available. Emperor names are for reference only and may be ambiguous when multiple emperors used the same era name.
 func (l LunarTime) LunarDescWithDynastyAndEmperor() []string {
 	return l.innerDescWithNianHao(true, true)
 }
@@ -299,6 +316,7 @@ func (l LunarTime) innerDescWithNianHao(withEmperor bool, withDynasty bool) []st
 // LunarInfo 农历结构化信息 / structured lunar information.
 //
 // 返回该农历结果对应的结构化农历信息切片；若存在多个并行年号，则会有多条记录。
+// Returns the structured lunar-calendar information for this result. Multiple records are returned when parallel era-name interpretations exist.
 func (l LunarTime) LunarInfo() []LunarInfo {
 	var res []LunarInfo
 	for _, v := range l.eras {

coord/airmass.go

@@ -5,6 +5,7 @@ import "b612.me/astro/formula"
 // AirmassPlaneParallelFromTrueAltitude 平行平板大气质量 / plane-parallel airmass from true altitude.
 //
 // 输入为真高度角，单位度。适合中高空几何近似，接近地平线时会发散。
+// Input is true altitude in degrees. This geometric approximation is suitable at moderate and high altitudes but diverges near the horizon.
 func AirmassPlaneParallelFromTrueAltitude(trueAltitude float64) float64 {
 	return formula.AirmassPlaneParallel(trueAltitude)
 }
@@ -12,6 +13,7 @@ func AirmassPlaneParallelFromTrueAltitude(trueAltitude float64) float64 {
 // AirmassKastenYoungFromApparentAltitude Kasten-Young 大气质量 / Kasten-Young airmass from apparent altitude.
 //
 // 输入为视高度角，单位度。
+// Input is apparent altitude in degrees.
 func AirmassKastenYoungFromApparentAltitude(apparentAltitude float64) float64 {
 	return formula.AirmassKastenYoung(apparentAltitude)
 }
@@ -19,6 +21,7 @@ func AirmassKastenYoungFromApparentAltitude(apparentAltitude float64) float64 {
 // AirmassPickeringFromApparentAltitude Pickering 大气质量 / Pickering airmass from apparent altitude.
 //
 // 输入为视高度角，单位度。
+// Input is apparent altitude in degrees.
 func AirmassPickeringFromApparentAltitude(apparentAltitude float64) float64 {
 	return formula.AirmassPickering(apparentAltitude)
 }
@@ -26,6 +29,7 @@ func AirmassPickeringFromApparentAltitude(apparentAltitude float64) float64 {
 // AirmassKastenYoungFromTrueAltitude Kasten-Young 大气质量 / Kasten-Young airmass from true altitude.
 //
 // 先用 pressureHPa / temperatureC 估算大气折射，将真高度角换算为视高度角，再代入经验公式。
+// First estimates atmospheric refraction from pressureHPa and temperatureC, converts true altitude to apparent altitude, and then applies the empirical formula.
 func AirmassKastenYoungFromTrueAltitude(trueAltitude, pressureHPa, temperatureC float64) float64 {
 	return formula.AirmassKastenYoung(ApparentAltitude(trueAltitude, pressureHPa, temperatureC))
 }
@@ -33,6 +37,7 @@ func AirmassKastenYoungFromTrueAltitude(trueAltitude, pressureHPa, temperatureC
 // AirmassPickeringFromTrueAltitude Pickering 大气质量 / Pickering airmass from true altitude.
 //
 // 先用 pressureHPa / temperatureC 估算大气折射，将真高度角换算为视高度角，再代入经验公式。
+// First estimates atmospheric refraction from pressureHPa and temperatureC, converts true altitude to apparent altitude, and then applies the empirical formula.
 func AirmassPickeringFromTrueAltitude(trueAltitude, pressureHPa, temperatureC float64) float64 {
 	return formula.AirmassPickering(ApparentAltitude(trueAltitude, pressureHPa, temperatureC))
 }

coord/refraction.go

@@ -9,6 +9,7 @@ import (
 // AtmosphericRefractionFromTrueAltitude 真高度角折射修正 / atmospheric refraction from true altitude.
 //
 // 输入真高度角，返回应加到真高度角上的大气折射修正量，单位度。
+// Takes true altitude and returns the atmospheric-refraction correction to be added to it, in degrees.
 func AtmosphericRefractionFromTrueAltitude(trueAltitude, pressureHPa, temperatureC float64) float64 {
 	return basic.RefractionFromTrueAltitude(trueAltitude, pressureHPa, temperatureC)
 }
@@ -16,6 +17,7 @@ func AtmosphericRefractionFromTrueAltitude(trueAltitude, pressureHPa, temperatur
 // AtmosphericRefractionFromApparentAltitude 视高度角折射修正 / atmospheric refraction from apparent altitude.
 //
 // 输入视高度角，返回对应的大气折射修正量，单位度。
+// Takes apparent altitude and returns the corresponding atmospheric-refraction correction, in degrees.
 func AtmosphericRefractionFromApparentAltitude(apparentAltitude, pressureHPa, temperatureC float64) float64 {
 	return basic.RefractionFromApparentAltitude(apparentAltitude, pressureHPa, temperatureC)
 }
@@ -23,6 +25,7 @@ func AtmosphericRefractionFromApparentAltitude(apparentAltitude, pressureHPa, te
 // ApparentAltitude 真高度角转视高度角 / apparent altitude from true altitude.
 //
 // 输入真高度角，返回加入标准大气折射后的视高度角，单位度。
+// Takes true altitude and returns the apparent altitude after applying standard atmospheric refraction, in degrees.
 func ApparentAltitude(trueAltitude, pressureHPa, temperatureC float64) float64 {
 	return basic.ApparentAltitude(trueAltitude, pressureHPa, temperatureC)
 }
@@ -30,6 +33,7 @@ func ApparentAltitude(trueAltitude, pressureHPa, temperatureC float64) float64 {
 // TrueAltitude 视高度角转真高度角 / true altitude from apparent altitude.
 //
 // 输入视高度角，返回去除大气折射后的真高度角，单位度。
+// Takes apparent altitude and returns the true altitude after removing atmospheric refraction, in degrees.
 func TrueAltitude(apparentAltitude, pressureHPa, temperatureC float64) float64 {
 	return basic.TrueAltitude(apparentAltitude, pressureHPa, temperatureC)
 }

coord/research.go

@@ -25,6 +25,8 @@ var icrsToGalacticMatrix = [3][3]float64{
 // 返回：
 //
 //	赤经 RA，单位度；赤纬 Dec，单位度
+//
+// Returns right ascension and declination in degrees for the supplied ecliptic longitude, latitude, and obliquity.
 func EclipticToEquatorialByObliquity(lon, lat, obliquity float64) Equatorial {
 	sinLon, cosLon := sinCosDeg(lon)
 	sinLat, cosLat := sinCosDeg(lat)
@@ -44,6 +46,8 @@ func EclipticToEquatorialByObliquity(lon, lat, obliquity float64) Equatorial {
 // 返回：
 //
 //	黄经 Lon，单位度；黄纬 Lat，单位度
+//
+// Returns ecliptic longitude and latitude in degrees for the supplied right ascension, declination, and obliquity.
 func EquatorialToEclipticByObliquity(ra, dec, obliquity float64) Ecliptic {
 	sinRA, cosRA := sinCosDeg(ra)
 	sinDec, cosDec := sinCosDeg(dec)
@@ -63,6 +67,8 @@ func EquatorialToEclipticByObliquity(ra, dec, obliquity float64) Ecliptic {
 // 返回：
 //
 //	方位角 Azimuth（正北为0，顺时针增加）、高度角 Altitude、天顶距 Zenith，均为度
+//
+// Returns azimuth, altitude, and zenith distance in degrees from the supplied hour angle, declination, and site latitude.
 func HourAngleDeclinationToHorizontal(hourAngle, declination, latitude float64) Horizontal {
 	sinLatitude, cosLatitude := sinCosDeg(latitude)
 	sinDeclination, cosDeclination := sinCosDeg(declination)
@@ -87,6 +93,8 @@ func HourAngleDeclinationToHorizontal(hourAngle, declination, latitude float64)
 // 返回：
 //
 //	时角 HourAngle，单位度；赤纬 Declination，单位度
+//
+// Returns hour angle and declination in degrees from the supplied horizontal coordinates and site latitude.
 func HorizontalToHourAngleDeclination(azimuth, altitude, latitude float64) (hourAngle, declination float64) {
 	sinLatitude, cosLatitude := sinCosDeg(latitude)
 	sinAltitude, cosAltitude := sinCosDeg(altitude)
@@ -111,6 +119,8 @@ func HorizontalToHourAngleDeclination(azimuth, altitude, latitude float64) (hour
 //	方位角 Azimuth（正北为0，顺时针增加）、高度角 Altitude、天顶距 Zenith，均为度；
 //	附带返回对应的时角 HourAngle，单位度
 //
+// Returns horizontal coordinates in degrees from local sidereal time, right ascension, declination, and site latitude.
+//
 // 例：
 //
 //	hz := coord.EquatorialToHorizontalByLocalSiderealTime(10.5, 83.6331, 22.0145, 31.2)
@@ -130,6 +140,8 @@ func EquatorialToHorizontalByLocalSiderealTime(localSiderealTimeHours, ra, dec,
 //
 //	赤经 RA，单位度；赤纬 Dec，单位度
 //
+// Returns right ascension and declination in degrees from local sidereal time and the supplied horizontal coordinates.
+//
 // 例：
 //
 //	eq := coord.HorizontalToEquatorialByLocalSiderealTime(10.5, 128.2, 37.6, 31.2)
@@ -147,6 +159,8 @@ func HorizontalToEquatorialByLocalSiderealTime(localSiderealTimeHours, azimuth,
 // 返回：
 //
 //	银经 Lon，单位度；银纬 Lat，单位度
+//
+// Returns galactic longitude and latitude in degrees from ICRS right ascension and declination.
 func EquatorialToGalactic(ra, dec float64) Galactic {
 	vector := sphericalToVector(ra, dec)
 	rotated := matrixVectorMul(icrsToGalacticMatrix, vector)
@@ -162,6 +176,8 @@ func EquatorialToGalactic(ra, dec float64) Galactic {
 // 返回：
 //
 //	ICRS 赤经 RA，单位度；ICRS 赤纬 Dec，单位度
+//
+// Returns ICRS right ascension and declination in degrees from galactic longitude and latitude.
 func GalacticToEquatorial(lon, lat float64) Equatorial {
 	vector := sphericalToVector(lon, lat)
 	rotated := matrixTransposeVectorMul(icrsToGalacticMatrix, vector)

formula/blackbody.go

@@ -18,6 +18,8 @@ const (
 // 返回：
 //
 //	峰值波长，单位米
+//
+// Returns the wavelength of maximum emission in meters for a blackbody at the supplied temperature.
 func WienPeakWavelength(temperatureK float64) float64 {
 	if temperatureK <= 0 || math.IsNaN(temperatureK) || math.IsInf(temperatureK, 0) {
 		return math.NaN()
@@ -32,6 +34,8 @@ func WienPeakWavelength(temperatureK float64) float64 {
 // 返回：
 //
 //	单位面积总出射度，单位 W/m^2
+//
+// Returns the total radiant exitance in W/m^2 for a blackbody at the supplied temperature.
 func StefanBoltzmannFlux(temperatureK float64) float64 {
 	if temperatureK < 0 || math.IsNaN(temperatureK) || math.IsInf(temperatureK, 0) {
 		return math.NaN()
@@ -48,6 +52,8 @@ func StefanBoltzmannFlux(temperatureK float64) float64 {
 //
 //	谱辐亮度，单位 W·sr^-1·m^-3
 //
+// Returns spectral radiance in W·sr^-1·m^-3 at the supplied wavelength and temperature.
+//
 // 例：
 //
 //	b := formula.PlanckRadianceByWavelength(500e-9, 5772)

formula/orbit.go

@@ -11,6 +11,8 @@ import "math"
 //
 //	会合周期，单位与输入相同
 //
+// Returns the synodic period in the same unit as the two input periods.
+//
 // 例：
 //
 //	// 地球与金星的会合周期，单位天

formula/photometry.go

@@ -9,6 +9,8 @@ import "math"
 // 返回：
 //
 //	距离模数 m-M
+//
+// Returns the distance modulus m-M for the supplied distance in parsecs.
 func DistanceModulus(distanceParsec float64) float64 {
 	if distanceParsec <= 0 || math.IsNaN(distanceParsec) || math.IsInf(distanceParsec, 0) {
 		return math.NaN()
@@ -24,6 +26,8 @@ func DistanceModulus(distanceParsec float64) float64 {
 // 返回：
 //
 //	视星等 m
+//
+// Returns apparent magnitude from absolute magnitude and distance.
 func ApparentMagnitudeFromAbsolute(absoluteMagnitude, distanceParsec float64) float64 {
 	modulus := DistanceModulus(distanceParsec)
 	if math.IsNaN(modulus) {
@@ -40,6 +44,8 @@ func ApparentMagnitudeFromAbsolute(absoluteMagnitude, distanceParsec float64) fl
 // 返回：
 //
 //	绝对星等 M
+//
+// Returns absolute magnitude from apparent magnitude and distance.
 func AbsoluteMagnitudeFromApparent(apparentMagnitude, distanceParsec float64) float64 {
 	modulus := DistanceModulus(distanceParsec)
 	if math.IsNaN(modulus) {

formula/stellar.go

@@ -16,6 +16,8 @@ const (
 // 返回：
 //
 //	总光度，单位瓦特
+//
+// Returns stellar luminosity in watts from radius and effective temperature.
 func LuminosityFromRadiusTemperature(radiusM, temperatureK float64) float64 {
 	if radiusM <= 0 || temperatureK <= 0 ||
 		math.IsNaN(radiusM) || math.IsInf(radiusM, 0) ||
@@ -33,6 +35,8 @@ func LuminosityFromRadiusTemperature(radiusM, temperatureK float64) float64 {
 // 返回：
 //
 //	恒星半径，单位米
+//
+// Returns stellar radius in meters from luminosity and effective temperature.
 func RadiusFromLuminosityTemperature(luminosityW, temperatureK float64) float64 {
 	if luminosityW <= 0 || temperatureK <= 0 ||
 		math.IsNaN(luminosityW) || math.IsInf(luminosityW, 0) ||
@@ -54,6 +58,8 @@ func RadiusFromLuminosityTemperature(luminosityW, temperatureK float64) float64
 // 返回：
 //
 //	恒星有效温度，单位开尔文
+//
+// Returns stellar effective temperature in kelvin from luminosity and radius.
 func EffectiveTemperatureFromLuminosityRadius(luminosityW, radiusM float64) float64 {
 	if luminosityW <= 0 || radiusM <= 0 ||
 		math.IsNaN(luminosityW) || math.IsInf(luminosityW, 0) ||
@@ -75,6 +81,8 @@ func EffectiveTemperatureFromLuminosityRadius(luminosityW, radiusM float64) floa
 // 返回：
 //
 //	总光度，单位为太阳光度 L☉
+//
+// Returns luminosity in solar units from radius in solar radii and effective temperature.
 func LuminositySolarFromRadiusTemperature(radiusSolar, temperatureK float64) float64 {
 	if radiusSolar <= 0 || temperatureK <= 0 ||
 		math.IsNaN(radiusSolar) || math.IsInf(radiusSolar, 0) ||
@@ -92,6 +100,8 @@ func LuminositySolarFromRadiusTemperature(radiusSolar, temperatureK float64) flo
 // 返回：
 //
 //	恒星半径，单位为太阳半径 R☉
+//
+// Returns radius in solar radii from luminosity in solar units and effective temperature.
 func RadiusSolarFromLuminosityTemperature(luminositySolar, temperatureK float64) float64 {
 	if luminositySolar <= 0 || temperatureK <= 0 ||
 		math.IsNaN(luminositySolar) || math.IsInf(luminositySolar, 0) ||
@@ -110,6 +120,8 @@ func RadiusSolarFromLuminosityTemperature(luminositySolar, temperatureK float64)
 //
 //	恒星有效温度，单位开尔文
 //
+// Returns stellar effective temperature in kelvin from luminosity and radius expressed in solar units.
+//
 // 例：
 //
 //	// 半径 2.5 R☉、光度 20 L☉ 的主序星
@@ -128,6 +140,8 @@ func EffectiveTemperatureFromLuminositySolarRadius(luminositySolar, radiusSolar
 // 返回：
 //
 //	太阳有效温度，单位开尔文
+//
+// Returns the adopted solar effective temperature constant in kelvin.
 func SolarEffectiveTemperature() float64 {
 	return solarEffectiveTempK
 }

formula/telescope.go

@@ -12,6 +12,8 @@ const darkAdaptedPupilDiameterMM = 7.0
 // 返回：
 //
 //	集光力比值，等于 (diameter1MM / diameter2MM)^2
+//
+// Returns the light-gathering power ratio, equal to (diameter1MM / diameter2MM)^2.
 func LightGatheringPowerRatio(diameter1MM, diameter2MM float64) float64 {
 	if diameter1MM <= 0 || diameter2MM <= 0 ||
 		math.IsNaN(diameter1MM) || math.IsInf(diameter1MM, 0) ||
@@ -28,6 +30,8 @@ func LightGatheringPowerRatio(diameter1MM, diameter2MM float64) float64 {
 // 返回：
 //
 //	Dawes 极限，单位角秒
+//
+// Returns the Dawes limit in arcseconds for the supplied aperture.
 func DawesLimitArcsec(diameterMM float64) float64 {
 	if diameterMM <= 0 || math.IsNaN(diameterMM) || math.IsInf(diameterMM, 0) {
 		return math.NaN()
@@ -42,6 +46,8 @@ func DawesLimitArcsec(diameterMM float64) float64 {
 // 返回：
 //
 //	Rayleigh 极限，单位角秒
+//
+// Returns the Rayleigh limit in arcseconds for the supplied aperture.
 func RayleighLimitArcsec(diameterMM float64) float64 {
 	if diameterMM <= 0 || math.IsNaN(diameterMM) || math.IsInf(diameterMM, 0) {
 		return math.NaN()
@@ -58,6 +64,8 @@ func RayleighLimitArcsec(diameterMM float64) float64 {
 //
 //	经验极限星等；这是经验值，不包含天空背景、倍率、透过率和观测经验修正
 //
+// Returns an empirical limiting magnitude estimate. It does not account for sky background, magnification, transmission, or observer skill.
+//
 // 例：
 //
 //	// 70mm 小型折射镜，裸眼极限 6 等

jupiter/jupiter.go

@@ -208,6 +208,7 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 // LastConjunction 上一次合日 / previous conjunction with the Sun.
 //
 // 返回 date 当前或之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastJupiterConjunction(jde), date.Location(), false)
@@ -216,6 +217,7 @@ func LastConjunction(date time.Time) time.Time {
 // NextConjunction 下一次合日 / next conjunction with the Sun.
 //
 // 返回 date 当前或之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextJupiterConjunction(jde), date.Location(), false)
@@ -224,6 +226,7 @@ func NextConjunction(date time.Time) time.Time {
 // LastOpposition 上一次冲日 / previous opposition.
 //
 // 返回 date 当前或之前最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or before date, keeping date's time zone.
 func LastOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastJupiterOpposition(jde), date.Location(), false)
@@ -232,6 +235,7 @@ func LastOpposition(date time.Time) time.Time {
 // NextOpposition 下一次冲日 / next opposition.
 //
 // 返回 date 当前或之后最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or after date, keeping date's time zone.
 func NextOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextJupiterOpposition(jde), date.Location(), false)
@@ -240,6 +244,7 @@ func NextOpposition(date time.Time) time.Time {
 // LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
 //
 // 返回 date 当前或之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastJupiterProgradeToRetrograde(jde), date.Location(), false)
@@ -248,6 +253,7 @@ func LastProgradeToRetrograde(date time.Time) time.Time {
 // NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
 //
 // 返回 date 当前或之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextJupiterProgradeToRetrograde(jde), date.Location(), false)
@@ -256,6 +262,7 @@ func NextProgradeToRetrograde(date time.Time) time.Time {
 // LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
 //
 // 返回 date 当前或之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastJupiterRetrogradeToPrograde(jde), date.Location(), false)
@@ -264,6 +271,7 @@ func LastRetrogradeToPrograde(date time.Time) time.Time {
 // NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
 //
 // 返回 date 当前或之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextJupiterRetrogradeToPrograde(jde), date.Location(), false)
@@ -272,6 +280,7 @@ func NextRetrogradeToPrograde(date time.Time) time.Time {
 // LastEasternQuadrature 上一次东方照 / previous eastern quadrature.
 //
 // 返回 date 当前或之前最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or before date, keeping date's time zone.
 func LastEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastJupiterEasternQuadrature(jde), date.Location(), false)
@@ -280,6 +289,7 @@ func LastEasternQuadrature(date time.Time) time.Time {
 // NextEasternQuadrature 下一次东方照 / next eastern quadrature.
 //
 // 返回 date 当前或之后最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or after date, keeping date's time zone.
 func NextEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextJupiterEasternQuadrature(jde), date.Location(), false)
@@ -288,6 +298,7 @@ func NextEasternQuadrature(date time.Time) time.Time {
 // LastWesternQuadrature 上一次西方照 / previous western quadrature.
 //
 // 返回 date 当前或之前最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or before date, keeping date's time zone.
 func LastWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastJupiterWesternQuadrature(jde), date.Location(), false)
@@ -296,6 +307,7 @@ func LastWesternQuadrature(date time.Time) time.Time {
 // NextWesternQuadrature 下一次西方照 / next western quadrature.
 //
 // 返回 date 当前或之后最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or after date, keeping date's time zone.
 func NextWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextJupiterWesternQuadrature(jde), date.Location(), false)

mars/mars.go

@@ -208,6 +208,7 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 // LastConjunction 上一次合日 / previous conjunction with the Sun.
 //
 // 返回 date 当前或之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMarsConjunction(jde), date.Location(), false)
@@ -216,6 +217,7 @@ func LastConjunction(date time.Time) time.Time {
 // NextConjunction 下一次合日 / next conjunction with the Sun.
 //
 // 返回 date 当前或之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMarsConjunction(jde), date.Location(), false)
@@ -224,6 +226,7 @@ func NextConjunction(date time.Time) time.Time {
 // LastOpposition 上一次冲日 / previous opposition.
 //
 // 返回 date 当前或之前最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or before date, keeping date's time zone.
 func LastOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMarsOpposition(jde), date.Location(), false)
@@ -232,6 +235,7 @@ func LastOpposition(date time.Time) time.Time {
 // NextOpposition 下一次冲日 / next opposition.
 //
 // 返回 date 当前或之后最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or after date, keeping date's time zone.
 func NextOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMarsOpposition(jde), date.Location(), false)
@@ -240,6 +244,7 @@ func NextOpposition(date time.Time) time.Time {
 // LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
 //
 // 返回 date 当前或之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMarsProgradeToRetrograde(jde), date.Location(), false)
@@ -248,6 +253,7 @@ func LastProgradeToRetrograde(date time.Time) time.Time {
 // NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
 //
 // 返回 date 当前或之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMarsProgradeToRetrograde(jde), date.Location(), false)
@@ -256,6 +262,7 @@ func NextProgradeToRetrograde(date time.Time) time.Time {
 // LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
 //
 // 返回 date 当前或之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMarsRetrogradeToPrograde(jde), date.Location(), false)
@@ -264,6 +271,7 @@ func LastRetrogradeToPrograde(date time.Time) time.Time {
 // NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
 //
 // 返回 date 当前或之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMarsRetrogradeToPrograde(jde), date.Location(), false)
@@ -272,6 +280,7 @@ func NextRetrogradeToPrograde(date time.Time) time.Time {
 // LastEasternQuadrature 上一次东方照 / previous eastern quadrature.
 //
 // 返回 date 当前或之前最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or before date, keeping date's time zone.
 func LastEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMarsEasternQuadrature(jde), date.Location(), false)
@@ -280,6 +289,7 @@ func LastEasternQuadrature(date time.Time) time.Time {
 // NextEasternQuadrature 下一次东方照 / next eastern quadrature.
 //
 // 返回 date 当前或之后最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or after date, keeping date's time zone.
 func NextEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMarsEasternQuadrature(jde), date.Location(), false)
@@ -288,6 +298,7 @@ func NextEasternQuadrature(date time.Time) time.Time {
 // LastWesternQuadrature 上一次西方照 / previous western quadrature.
 //
 // 返回 date 当前或之前最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or before date, keeping date's time zone.
 func LastWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMarsWesternQuadrature(jde), date.Location(), false)
@@ -296,6 +307,7 @@ func LastWesternQuadrature(date time.Time) time.Time {
 // NextWesternQuadrature 下一次西方照 / next western quadrature.
 //
 // 返回 date 当前或之后最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or after date, keeping date's time zone.
 func NextWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMarsWesternQuadrature(jde), date.Location(), false)

mercury/mercury.go

@@ -208,6 +208,7 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 // LastConjunction 上一次合日 / previous conjunction with the Sun.
 //
 // 返回 date 当前或之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryConjunction(jde), date.Location(), false)
@@ -216,6 +217,7 @@ func LastConjunction(date time.Time) time.Time {
 // NextConjunction 下一次合日 / next conjunction with the Sun.
 //
 // 返回 date 当前或之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryConjunction(jde), date.Location(), false)
@@ -224,6 +226,7 @@ func NextConjunction(date time.Time) time.Time {
 // LastInferiorConjunction 上一次下合 / previous inferior conjunction.
 //
 // 返回 date 当前或之前最近一次下合时刻，结果保持 date 的时区。
+// Returns the nearest inferior conjunction at or before date, keeping date's time zone.
 func LastInferiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryInferiorConjunctionInclusive(jde), date.Location(), false)
@@ -232,6 +235,7 @@ func LastInferiorConjunction(date time.Time) time.Time {
 // NextInferiorConjunction 下一次下合 / next inferior conjunction.
 //
 // 返回 date 当前或之后最近一次下合时刻，结果保持 date 的时区。
+// Returns the nearest inferior conjunction at or after date, keeping date's time zone.
 func NextInferiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryInferiorConjunctionInclusive(jde), date.Location(), false)
@@ -240,6 +244,7 @@ func NextInferiorConjunction(date time.Time) time.Time {
 // LastSuperiorConjunction 上一次上合 / previous superior conjunction.
 //
 // 返回 date 当前或之前最近一次上合时刻，结果保持 date 的时区。
+// Returns the nearest superior conjunction at or before date, keeping date's time zone.
 func LastSuperiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercurySuperiorConjunctionInclusive(jde), date.Location(), false)
@@ -248,6 +253,7 @@ func LastSuperiorConjunction(date time.Time) time.Time {
 // NextSuperiorConjunction 下一次上合 / next superior conjunction.
 //
 // 返回 date 当前或之后最近一次上合时刻，结果保持 date 的时区。
+// Returns the nearest superior conjunction at or after date, keeping date's time zone.
 func NextSuperiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercurySuperiorConjunctionInclusive(jde), date.Location(), false)
@@ -256,6 +262,7 @@ func NextSuperiorConjunction(date time.Time) time.Time {
 // LastRetrograde 上一次留 / previous stationary point.
 //
 // 返回 date 当前或之前最近一次留时刻，不区分顺转逆还是逆转顺，结果保持 date 的时区。
+// Returns the nearest stationary point at or before date, regardless of the direction change, keeping date's time zone.
 func LastRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryRetrogradeInclusive(jde), date.Location(), false)
@@ -264,6 +271,7 @@ func LastRetrograde(date time.Time) time.Time {
 // NextRetrograde 下一次留 / next stationary point.
 //
 // 返回 date 当前或之后最近一次留时刻，不区分顺转逆还是逆转顺，结果保持 date 的时区。
+// Returns the nearest stationary point at or after date, regardless of the direction change, keeping date's time zone.
 func NextRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryRetrogradeInclusive(jde), date.Location(), false)
@@ -272,6 +280,7 @@ func NextRetrograde(date time.Time) time.Time {
 // LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
 //
 // 返回 date 当前或之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryProgradeToRetrogradeInclusive(jde), date.Location(), false)
@@ -280,6 +289,7 @@ func LastProgradeToRetrograde(date time.Time) time.Time {
 // NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
 //
 // 返回 date 当前或之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryProgradeToRetrogradeInclusive(jde), date.Location(), false)
@@ -288,6 +298,7 @@ func NextProgradeToRetrograde(date time.Time) time.Time {
 // LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
 //
 // 返回 date 当前或之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryRetrogradeToProgradeInclusive(jde), date.Location(), false)
@@ -296,6 +307,7 @@ func LastRetrogradeToPrograde(date time.Time) time.Time {
 // NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
 //
 // 返回 date 当前或之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryRetrogradeToProgradeInclusive(jde), date.Location(), false)
@@ -304,6 +316,7 @@ func NextRetrogradeToPrograde(date time.Time) time.Time {
 // LastGreatestElongation 上一次大距 / previous greatest elongation.
 //
 // 返回 date 当前或之前最近一次大距时刻，不区分东西大距，结果保持 date 的时区。
+// Returns the nearest greatest elongation at or before date, regardless of east or west, keeping date's time zone.
 func LastGreatestElongation(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryGreatestElongationInclusive(jde), date.Location(), false)
@@ -312,6 +325,7 @@ func LastGreatestElongation(date time.Time) time.Time {
 // NextGreatestElongation 下一次大距 / next greatest elongation.
 //
 // 返回 date 当前或之后最近一次大距时刻，不区分东西大距，结果保持 date 的时区。
+// Returns the nearest greatest elongation at or after date, regardless of east or west, keeping date's time zone.
 func NextGreatestElongation(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryGreatestElongationInclusive(jde), date.Location(), false)
@@ -320,6 +334,7 @@ func NextGreatestElongation(date time.Time) time.Time {
 // LastGreatestElongationEast 上一次东大距 / previous greatest eastern elongation.
 //
 // 返回 date 当前或之前最近一次东大距时刻，结果保持 date 的时区。
+// Returns the nearest eastern greatest elongation at or before date, keeping date's time zone.
 func LastGreatestElongationEast(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryGreatestElongationEastInclusive(jde), date.Location(), false)
@@ -328,6 +343,7 @@ func LastGreatestElongationEast(date time.Time) time.Time {
 // NextGreatestElongationEast 下一次东大距 / next greatest eastern elongation.
 //
 // 返回 date 当前或之后最近一次东大距时刻，结果保持 date 的时区。
+// Returns the nearest eastern greatest elongation at or after date, keeping date's time zone.
 func NextGreatestElongationEast(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryGreatestElongationEastInclusive(jde), date.Location(), false)
@@ -336,6 +352,7 @@ func NextGreatestElongationEast(date time.Time) time.Time {
 // LastGreatestElongationWest 上一次西大距 / previous greatest western elongation.
 //
 // 返回 date 当前或之前最近一次西大距时刻，结果保持 date 的时区。
+// Returns the nearest western greatest elongation at or before date, keeping date's time zone.
 func LastGreatestElongationWest(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastMercuryGreatestElongationWestInclusive(jde), date.Location(), false)
@@ -344,6 +361,7 @@ func LastGreatestElongationWest(date time.Time) time.Time {
 // NextGreatestElongationWest 下一次西大距 / next greatest western elongation.
 //
 // 返回 date 当前或之后最近一次西大距时刻，结果保持 date 的时区。
+// Returns the nearest western greatest elongation at or after date, keeping date's time zone.
 func NextGreatestElongationWest(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextMercuryGreatestElongationWestInclusive(jde), date.Location(), false)

moon/conjunction_test.go

@@ -80,3 +80,24 @@ func TestInvalidConjunctionPlanetReturnsZeroTime(t *testing.T) {
 		}
 	}
 }
+
+func TestNextConjunctionAdvancesPastReturnedEvent(t *testing.T) {
+	cursor := time.Date(2026, 5, 1, 0, 0, 0, 0, time.UTC)
+	first := NextConjunctionWithPlanet(cursor, ConjunctionMercury)
+	query := first.Add(time.Second)
+	next := NextConjunctionWithPlanet(query, ConjunctionMercury)
+
+	if !next.After(query) {
+		t.Fatalf("expected next conjunction after query: query=%s next=%s delta=%v",
+			query.Format(time.RFC3339Nano),
+			next.Format(time.RFC3339Nano),
+			next.Sub(query),
+		)
+	}
+	if next.Equal(first) {
+		t.Fatalf("expected next conjunction to advance: first=%s next=%s",
+			first.Format(time.RFC3339Nano),
+			next.Format(time.RFC3339Nano),
+		)
+	}
+}

neptune/neptune.go

@@ -208,6 +208,7 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 // LastConjunction 上一次合日 / previous conjunction with the Sun.
 //
 // 返回 date 当前或之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastNeptuneConjunction(jde), date.Location(), false)
@@ -216,6 +217,7 @@ func LastConjunction(date time.Time) time.Time {
 // NextConjunction 下一次合日 / next conjunction with the Sun.
 //
 // 返回 date 当前或之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextNeptuneConjunction(jde), date.Location(), false)
@@ -224,6 +226,7 @@ func NextConjunction(date time.Time) time.Time {
 // LastOpposition 上一次冲日 / previous opposition.
 //
 // 返回 date 当前或之前最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or before date, keeping date's time zone.
 func LastOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastNeptuneOpposition(jde), date.Location(), false)
@@ -232,6 +235,7 @@ func LastOpposition(date time.Time) time.Time {
 // NextOpposition 下一次冲日 / next opposition.
 //
 // 返回 date 当前或之后最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or after date, keeping date's time zone.
 func NextOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextNeptuneOpposition(jde), date.Location(), false)
@@ -240,6 +244,7 @@ func NextOpposition(date time.Time) time.Time {
 // LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
 //
 // 返回 date 当前或之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastNeptuneProgradeToRetrograde(jde), date.Location(), false)
@@ -248,6 +253,7 @@ func LastProgradeToRetrograde(date time.Time) time.Time {
 // NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
 //
 // 返回 date 当前或之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextNeptuneProgradeToRetrograde(jde), date.Location(), false)
@@ -256,6 +262,7 @@ func NextProgradeToRetrograde(date time.Time) time.Time {
 // LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
 //
 // 返回 date 当前或之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastNeptuneRetrogradeToPrograde(jde), date.Location(), false)
@@ -264,6 +271,7 @@ func LastRetrogradeToPrograde(date time.Time) time.Time {
 // NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
 //
 // 返回 date 当前或之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextNeptuneRetrogradeToPrograde(jde), date.Location(), false)
@@ -272,6 +280,7 @@ func NextRetrogradeToPrograde(date time.Time) time.Time {
 // LastEasternQuadrature 上一次东方照 / previous eastern quadrature.
 //
 // 返回 date 当前或之前最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or before date, keeping date's time zone.
 func LastEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastNeptuneEasternQuadrature(jde), date.Location(), false)
@@ -280,6 +289,7 @@ func LastEasternQuadrature(date time.Time) time.Time {
 // NextEasternQuadrature 下一次东方照 / next eastern quadrature.
 //
 // 返回 date 当前或之后最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or after date, keeping date's time zone.
 func NextEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextNeptuneEasternQuadrature(jde), date.Location(), false)
@@ -288,6 +298,7 @@ func NextEasternQuadrature(date time.Time) time.Time {
 // LastWesternQuadrature 上一次西方照 / previous western quadrature.
 //
 // 返回 date 当前或之前最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or before date, keeping date's time zone.
 func LastWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastNeptuneWesternQuadrature(jde), date.Location(), false)
@@ -296,6 +307,7 @@ func LastWesternQuadrature(date time.Time) time.Time {
 // NextWesternQuadrature 下一次西方照 / next western quadrature.
 //
 // 返回 date 当前或之后最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or after date, keeping date's time zone.
 func NextWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextNeptuneWesternQuadrature(jde), date.Location(), false)

orbit/orbit.go

@@ -12,13 +12,17 @@ var (
 	ERR_ORBIT_NEVER_SET  = errors.New("ERROR:轨道目标今日永远在地平线上！")
 )
 
-// Elements 日心二体圆锥曲线根数，参考系为 J2000 平黄道/平春分点。
+// Elements 日心二体圆锥曲线根数 / heliocentric two-body conic elements.
+// 参考系为 J2000 平黄道/平春分点。
+// The reference frame is the J2000 mean ecliptic and mean equinox.
 // EpochJD 与 TpJD 使用 TT/TDB 对应的儒略日。
+// EpochJD and TpJD are Julian days on the TT/TDB scale.
 //
 // 经典椭圆根数：A/E/I/Omega/W/M0
 // 近日点形式：Q/E/I/Omega/W/TpJD
 //
 // 线性 rates 仅作用于经典椭圆根数，单位均为每天变化量。
+// The linear rates apply only to the classical elliptical element form and are expressed per day.
 type Elements struct {
 	EpochJD float64 // 历元儒略日（TT/TDB） / epoch Julian day in TT/TDB.
 	A       float64 // 半长径，单位 AU / semi-major axis in AU.
@@ -38,14 +42,20 @@ type Elements struct {
 	MDot     float64 // 平近点角日变化，单位 deg/day / daily rate of M.
 }
 
-// EclipticPosition 黄道球坐标结果，Lon/Lat 单位度，Distance 单位 AU。
+// EclipticPosition 黄道球坐标结果 / ecliptic spherical coordinates.
+//
+// Lon/Lat 单位度，Distance 单位 AU。
+// Lon/Lat are in degrees and Distance is in AU.
 type EclipticPosition struct {
 	Lon      float64
 	Lat      float64
 	Distance float64
 }
 
-// EquatorialPosition 赤道球坐标结果，RA/Dec 单位度，Distance 单位 AU。
+// EquatorialPosition 赤道球坐标结果 / equatorial spherical coordinates.
+//
+// RA/Dec 单位度，Distance 单位 AU。
+// RA/Dec are in degrees and Distance is in AU.
 type EquatorialPosition struct {
 	RA       float64
 	Dec      float64
@@ -55,6 +65,7 @@ type EquatorialPosition struct {
 // MeanMotion 平均角速度 / mean motion.
 //
 // 返回平均角速度，单位度/日；对抛物线和双曲线轨道返回 `NaN`。
+// Returns mean motion in degrees per day. Parabolic and hyperbolic cases return `NaN`.
 func MeanMotion(elements Elements) float64 {
 	return basic.OrbitMeanMotion(toBasicElements(elements))
 }
@@ -62,6 +73,7 @@ func MeanMotion(elements Elements) float64 {
 // MeanAnomaly 平近点角 / mean anomaly.
 //
 // 返回给定时刻的平近点角，单位度；对抛物线和双曲线轨道返回 `NaN`。
+// Returns mean anomaly in degrees for the supplied instant. Parabolic and hyperbolic cases return `NaN`.
 func MeanAnomaly(date time.Time, elements Elements) float64 {
 	return basic.OrbitMeanAnomaly(ttJulianDay(date), toBasicElements(elements))
 }
@@ -69,6 +81,7 @@ func MeanAnomaly(date time.Time, elements Elements) float64 {
 // TrueAnomaly 真近点角 / true anomaly.
 //
 // 返回给定时刻的真近点角，单位度。
+// Returns true anomaly in degrees for the supplied instant.
 func TrueAnomaly(date time.Time, elements Elements) float64 {
 	return basic.OrbitTrueAnomaly(ttJulianDay(date), toBasicElements(elements))
 }
@@ -76,6 +89,7 @@ func TrueAnomaly(date time.Time, elements Elements) float64 {
 // HeliocentricEclipticJ2000 日心 J2000 平黄道坐标 / heliocentric J2000 ecliptic coordinates.
 //
 // 返回黄经、黄纬和距离；角度单位度，距离单位 AU。
+// Returns heliocentric J2000 ecliptic longitude, latitude, and distance. Angles are in degrees and distance is in AU.
 func HeliocentricEclipticJ2000(date time.Time, elements Elements) EclipticPosition {
 	lon, lat, distance := basic.OrbitHeliocentricEclipticJ2000(ttJulianDay(date), toBasicElements(elements))
 	return EclipticPosition{Lon: lon, Lat: lat, Distance: distance}
@@ -84,6 +98,7 @@ func HeliocentricEclipticJ2000(date time.Time, elements Elements) EclipticPositi
 // HeliocentricEcliptic 日心历元黄道坐标 / heliocentric ecliptic coordinates of date.
 //
 // 返回历元黄经、黄纬和距离；角度单位度，距离单位 AU。
+// Returns heliocentric ecliptic longitude, latitude, and distance of date. Angles are in degrees and distance is in AU.
 func HeliocentricEcliptic(date time.Time, elements Elements) EclipticPosition {
 	lon, lat, distance := basic.OrbitHeliocentricEcliptic(ttJulianDay(date), toBasicElements(elements))
 	return EclipticPosition{Lon: lon, Lat: lat, Distance: distance}
@@ -92,6 +107,7 @@ func HeliocentricEcliptic(date time.Time, elements Elements) EclipticPosition {
 // GeocentricEclipticJ2000 地心 J2000 平黄道坐标 / geocentric J2000 ecliptic coordinates.
 //
 // 返回黄经、黄纬和距离；角度单位度，距离单位 AU。
+// Returns geocentric J2000 ecliptic longitude, latitude, and distance. Angles are in degrees and distance is in AU.
 func GeocentricEclipticJ2000(date time.Time, elements Elements) EclipticPosition {
 	lon, lat, distance := basic.OrbitGeocentricEclipticJ2000(ttJulianDay(date), toBasicElements(elements))
 	return EclipticPosition{Lon: lon, Lat: lat, Distance: distance}
@@ -100,6 +116,7 @@ func GeocentricEclipticJ2000(date time.Time, elements Elements) EclipticPosition
 // GeocentricEcliptic 地心历元黄道坐标 / geocentric ecliptic coordinates of date.
 //
 // 返回历元黄经、黄纬和距离；角度单位度，距离单位 AU。
+// Returns geocentric ecliptic longitude, latitude, and distance of date. Angles are in degrees and distance is in AU.
 func GeocentricEcliptic(date time.Time, elements Elements) EclipticPosition {
 	lon, lat, distance := basic.OrbitGeocentricEcliptic(ttJulianDay(date), toBasicElements(elements))
 	return EclipticPosition{Lon: lon, Lat: lat, Distance: distance}
@@ -108,6 +125,7 @@ func GeocentricEcliptic(date time.Time, elements Elements) EclipticPosition {
 // GeocentricEquatorialJ2000 地心 J2000 平赤道坐标 / geocentric J2000 equatorial coordinates.
 //
 // 返回赤经、赤纬和距离；角度单位度，距离单位 AU。
+// Returns geocentric J2000 right ascension, declination, and distance. Angles are in degrees and distance is in AU.
 func GeocentricEquatorialJ2000(date time.Time, elements Elements) EquatorialPosition {
 	ra, dec, distance := basic.OrbitGeocentricEquatorialJ2000(ttJulianDay(date), toBasicElements(elements))
 	return EquatorialPosition{RA: ra, Dec: dec, Distance: distance}
@@ -116,6 +134,7 @@ func GeocentricEquatorialJ2000(date time.Time, elements Elements) EquatorialPosi
 // GeocentricEquatorial 地心历元平赤道坐标 / geocentric equatorial coordinates of date.
 //
 // 返回历元赤经、赤纬和距离；角度单位度，距离单位 AU。
+// Returns geocentric right ascension, declination, and distance of date. Angles are in degrees and distance is in AU.
 func GeocentricEquatorial(date time.Time, elements Elements) EquatorialPosition {
 	ra, dec, distance := basic.OrbitGeocentricEquatorial(ttJulianDay(date), toBasicElements(elements))
 	return EquatorialPosition{RA: ra, Dec: dec, Distance: distance}
@@ -124,6 +143,7 @@ func GeocentricEquatorial(date time.Time, elements Elements) EquatorialPosition
 // AstrometricGeocentricEquatorialJ2000 地心测算 J2000 赤道坐标 / astrometric geocentric J2000 equatorial coordinates.
 //
 // 返回加入光行时修正后的地心 J2000 赤经、赤纬和距离；角度单位度，距离单位 AU。
+// Returns astrometric geocentric J2000 right ascension, declination, and distance after light-time correction. Angles are in degrees and distance is in AU.
 func AstrometricGeocentricEquatorialJ2000(date time.Time, elements Elements) EquatorialPosition {
 	ra, dec, distance := basic.OrbitAstrometricGeocentricEquatorialJ2000(ttJulianDay(date), toBasicElements(elements))
 	return EquatorialPosition{RA: ra, Dec: dec, Distance: distance}
@@ -132,6 +152,7 @@ func AstrometricGeocentricEquatorialJ2000(date time.Time, elements Elements) Equ
 // ApparentGeocentricEcliptic 地心视黄道坐标 / apparent geocentric ecliptic coordinates.
 //
 // 返回加入光行时与章动修正后的地心视黄经、黄纬和距离；角度单位度，距离单位 AU。
+// Returns apparent geocentric ecliptic longitude, latitude, and distance after light-time and nutation corrections. Angles are in degrees and distance is in AU.
 func ApparentGeocentricEcliptic(date time.Time, elements Elements) EclipticPosition {
 	lon, lat, distance := basic.OrbitApparentGeocentricEcliptic(ttJulianDay(date), toBasicElements(elements))
 	return EclipticPosition{Lon: lon, Lat: lat, Distance: distance}
@@ -140,6 +161,7 @@ func ApparentGeocentricEcliptic(date time.Time, elements Elements) EclipticPosit
 // ApparentGeocentricEquatorial 地心视赤道坐标 / apparent geocentric equatorial coordinates.
 //
 // 返回加入光行时与章动修正后的地心视赤经、赤纬和距离；角度单位度，距离单位 AU。
+// Returns apparent geocentric right ascension, declination, and distance after light-time and nutation corrections. Angles are in degrees and distance is in AU.
 func ApparentGeocentricEquatorial(date time.Time, elements Elements) EquatorialPosition {
 	ra, dec, distance := basic.OrbitApparentGeocentricEquatorial(ttJulianDay(date), toBasicElements(elements))
 	return EquatorialPosition{RA: ra, Dec: dec, Distance: distance}
@@ -149,6 +171,7 @@ func ApparentGeocentricEquatorial(date time.Time, elements Elements) EquatorialP
 //
 // 返回加入光行时、章动和站心修正后的视赤经、赤纬和距离；
 // `observerLon` 东经为正，`observerLat` 北纬为正，`observerHeight` 单位米。
+// Returns apparent topocentric right ascension, declination, and distance after light-time, nutation, and topocentric corrections.
 func ApparentTopocentricEquatorial(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64) EquatorialPosition {
 	ra, dec, distance := basic.OrbitApparentTopocentricEquatorial(ttJulianDay(date), observerLon, observerLat, observerHeight, toBasicElements(elements))
 	return EquatorialPosition{RA: ra, Dec: dec, Distance: distance}
@@ -157,6 +180,7 @@ func ApparentTopocentricEquatorial(date time.Time, elements Elements, observerLo
 // Altitude 视高度角 / apparent altitude.
 //
 // 返回目标在观测者所在地的视高度角，单位度；经度东正西负，纬度北正南负，海拔单位米。
+// Returns the apparent altitude of the target for the observing site, in degrees. Longitude is east-positive, latitude is north-positive, and height is in meters.
 func Altitude(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64) float64 {
 	jde := basic.Date2JDE(date)
 	return basic.OrbitHeight(jde, observerLon, observerLat, observationTimezone(date), observerHeight, toBasicElements(elements))
@@ -165,6 +189,7 @@ func Altitude(date time.Time, elements Elements, observerLon, observerLat, obser
 // Zenith 天顶距 / zenith distance.
 //
 // 返回目标在观测者所在地的天顶距，单位度。
+// Returns the zenith distance of the target for the observing site, in degrees.
 func Zenith(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64) float64 {
 	return 90 - Altitude(date, elements, observerLon, observerLat, observerHeight)
 }
@@ -172,6 +197,7 @@ func Zenith(date time.Time, elements Elements, observerLon, observerLat, observe
 // Azimuth 视方位角 / apparent azimuth.
 //
 // 返回目标在观测者所在地的视方位角，按正北为 0°、向东增加。
+// Returns the apparent azimuth of the target for the observing site, measured from north toward east.
 func Azimuth(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64) float64 {
 	jde := basic.Date2JDE(date)
 	return basic.OrbitAzimuth(jde, observerLon, observerLat, observationTimezone(date), observerHeight, toBasicElements(elements))
@@ -180,6 +206,7 @@ func Azimuth(date time.Time, elements Elements, observerLon, observerLat, observ
 // HourAngle 站心视时角 / topocentric hour angle.
 //
 // 返回目标在观测者所在地的站心视时角，单位度。
+// Returns the apparent topocentric hour angle of the target for the observing site, in degrees.
 func HourAngle(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64) float64 {
 	jde := basic.Date2JDE(date)
 	return basic.OrbitHourAngle(jde, observerLon, observerLat, observationTimezone(date), observerHeight, toBasicElements(elements))
@@ -188,6 +215,7 @@ func HourAngle(date time.Time, elements Elements, observerLon, observerLat, obse
 // CulminationTime 中天时刻 / culmination time.
 //
 // 返回目标在给定当地日期内的中天时刻，结果保持输入 `date` 的时区。
+// Returns the culmination time of the target on the supplied local civil day. The result keeps the timezone of `date`.
 func CulminationTime(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64) time.Time {
 	if date.Hour() > 12 {
 		date = date.Add(-12 * time.Hour)
@@ -201,6 +229,7 @@ func CulminationTime(date time.Time, elements Elements, observerLon, observerLat
 // RiseTime 升起时刻 / rise time.
 //
 // 返回目标在给定当地日期内的升起时刻；`aero=true` 时加入标准大气折射修正。
+// Returns the rise time of the target on the supplied local civil day. When `aero` is true, standard atmospheric refraction is included.
 func RiseTime(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64, aero bool) (time.Time, error) {
 	var aeroFloat float64
 	if aero {
@@ -218,6 +247,7 @@ func RiseTime(date time.Time, elements Elements, observerLon, observerLat, obser
 // SetTime 落下时刻 / set time.
 //
 // 返回目标在给定当地日期内的落下时刻；`aero=true` 时加入标准大气折射修正。
+// Returns the set time of the target on the supplied local civil day. When `aero` is true, standard atmospheric refraction is included.
 func SetTime(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64, aero bool) (time.Time, error) {
 	var aeroFloat float64
 	if aero {

orbit/parallactic.go

@@ -9,6 +9,7 @@ import (
 // ParallacticAngle 轨道目标视差角（天顶方向角） / orbit-target parallactic angle.
 //
 // 返回轨道目标在观测者所在地的视差角，单位度；`observerLon` 东经为正，`observerLat` 北纬为正，`observerHeight` 单位米。
+// Returns the parallactic angle of the orbital target for the observing site, in degrees. `observerLon` is east-positive, `observerLat` is north-positive, and `observerHeight` is in meters.
 func ParallacticAngle(date time.Time, elements Elements, observerLon, observerLat, observerHeight float64) float64 {
 	position := ApparentTopocentricEquatorial(date, elements, observerLon, observerLat, observerHeight)
 	return basic.ParallacticAngleByHourAngle(

orbit/visual_binary.go

@@ -8,7 +8,10 @@ import (
 const visualBinaryDeg = 180 / math.Pi
 const visualBinaryRad = math.Pi / 180
 
-// VisualBinaryElements 视双星轨道要素，采用《天文算法》第 55 章的经典口径。
+// VisualBinaryElements 视双星轨道要素 / visual-binary orbital elements.
+//
+// 采用《天文算法》第 55 章的经典口径。
+// Uses the classical convention described in Chapter 55 of Astronomical Algorithms.
 type VisualBinaryElements struct {
 	PeriodYears        float64 // 周期 P，单位平太阳年 / orbital period in mean solar years.
 	PeriastronYear     float64 // 过近星点时刻 T，采用带小数的年 / epoch of periastron as a decimal year.
@@ -19,7 +22,7 @@ type VisualBinaryElements struct {
 	PeriastronArgument float64 // 近星点角距 ω，单位度 / argument of periastron in degrees.
 }
 
-// VisualBinaryPosition 视双星在天球上的计算结果。
+// VisualBinaryPosition 视双星在天球上的计算结果 / computed sky-plane position of a visual binary.
 type VisualBinaryPosition struct {
 	Year             float64 // 计算使用的小数年 / decimal year used for the evaluation.
 	MeanAnomaly      float64 // 平近点角 M，单位度 / mean anomaly in degrees.
@@ -41,6 +44,7 @@ func VisualBinary(date time.Time, elements VisualBinaryElements) VisualBinaryPos
 // VisualBinaryByYear 视双星位置（按小数年） / visual binary position by decimal year.
 //
 // 返回给定小数年对应的视双星位置角和角距离。
+// Returns the position angle and apparent separation for the supplied decimal year.
 func VisualBinaryByYear(year float64, elements VisualBinaryElements) VisualBinaryPosition {
 	if !validVisualBinaryElements(year, elements) {
 		return invalidVisualBinaryPosition(year)

saturn/saturn.go

@@ -208,6 +208,7 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 // LastConjunction 上一次合日 / previous conjunction with the Sun.
 //
 // 返回 date 当前或之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastSaturnConjunction(jde), date.Location(), false)
@@ -216,6 +217,7 @@ func LastConjunction(date time.Time) time.Time {
 // NextConjunction 下一次合日 / next conjunction with the Sun.
 //
 // 返回 date 当前或之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextSaturnConjunction(jde), date.Location(), false)
@@ -224,6 +226,7 @@ func NextConjunction(date time.Time) time.Time {
 // LastOpposition 上一次冲日 / previous opposition.
 //
 // 返回 date 当前或之前最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or before date, keeping date's time zone.
 func LastOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastSaturnOpposition(jde), date.Location(), false)
@@ -232,6 +235,7 @@ func LastOpposition(date time.Time) time.Time {
 // NextOpposition 下一次冲日 / next opposition.
 //
 // 返回 date 当前或之后最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or after date, keeping date's time zone.
 func NextOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextSaturnOpposition(jde), date.Location(), false)
@@ -240,6 +244,7 @@ func NextOpposition(date time.Time) time.Time {
 // LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
 //
 // 返回 date 当前或之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastSaturnProgradeToRetrograde(jde), date.Location(), false)
@@ -248,6 +253,7 @@ func LastProgradeToRetrograde(date time.Time) time.Time {
 // NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
 //
 // 返回 date 当前或之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextSaturnProgradeToRetrograde(jde), date.Location(), false)
@@ -256,6 +262,7 @@ func NextProgradeToRetrograde(date time.Time) time.Time {
 // LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
 //
 // 返回 date 当前或之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastSaturnRetrogradeToPrograde(jde), date.Location(), false)
@@ -264,6 +271,7 @@ func LastRetrogradeToPrograde(date time.Time) time.Time {
 // NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
 //
 // 返回 date 当前或之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextSaturnRetrogradeToPrograde(jde), date.Location(), false)
@@ -272,6 +280,7 @@ func NextRetrogradeToPrograde(date time.Time) time.Time {
 // LastEasternQuadrature 上一次东方照 / previous eastern quadrature.
 //
 // 返回 date 当前或之前最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or before date, keeping date's time zone.
 func LastEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastSaturnEasternQuadrature(jde), date.Location(), false)
@@ -280,6 +289,7 @@ func LastEasternQuadrature(date time.Time) time.Time {
 // NextEasternQuadrature 下一次东方照 / next eastern quadrature.
 //
 // 返回 date 当前或之后最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or after date, keeping date's time zone.
 func NextEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextSaturnEasternQuadrature(jde), date.Location(), false)
@@ -288,6 +298,7 @@ func NextEasternQuadrature(date time.Time) time.Time {
 // LastWesternQuadrature 上一次西方照 / previous western quadrature.
 //
 // 返回 date 当前或之前最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or before date, keeping date's time zone.
 func LastWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastSaturnWesternQuadrature(jde), date.Location(), false)
@@ -296,6 +307,7 @@ func LastWesternQuadrature(date time.Time) time.Time {
 // NextWesternQuadrature 下一次西方照 / next western quadrature.
 //
 // 返回 date 当前或之后最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or after date, keeping date's time zone.
 func NextWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextSaturnWesternQuadrature(jde), date.Location(), false)

star/parallactic.go

@@ -10,6 +10,8 @@ import (
 //
 // ra/dec 为瞬时赤经赤纬，单位度；lon/lat 为观测者经纬度，东正西负、北正南负。
 // 返回值为有符号视差角，单位度。
+// ra/dec are apparent equatorial coordinates in degrees; lon/lat are east-positive and north-positive.
+// Returns the signed parallactic angle in degrees.
 func ParallacticAngle(date time.Time, ra, dec, lon, lat float64) float64 {
 	jde := basic.Date2JDE(date)
 	_, loc := date.Zone()

sun/sun.go

@@ -100,6 +100,8 @@ func DownTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, e
 
 // DownTimeN 截断项日落时刻别名 / deprecated truncated sunset alias.
 //
+// Deprecated: use SetTimeN instead.
+//
 // 参数与 SetTimeN 相同，仅为兼容旧接口保留。
 // Same as SetTimeN and kept only for backward compatibility.
 func DownTimeN(date time.Time, lon, lat, height float64, aero bool, n int) (time.Time, error) {

sundial/planar.go

@@ -15,6 +15,12 @@ import (
 //
 // 坐标系沿本章通用约定：x 轴位于盘面内且保持水平，y 轴沿盘面最大坡度向上，
 // x 正向为右侧，y 正向为上坡方向。
+// Latitude is geographic latitude, north positive. PlaneNormalAzimuth is the azimuth of the dial-plane normal,
+// measured from north toward east. PlaneNormalZenithDistance is the zenith distance of the plane normal:
+// 0 degrees for a horizontal dial and 90 degrees for a vertical dial. StylusLength is the length of the direct stylus normal to the plane.
+//
+// The plane coordinates follow the chapter convention: the x axis lies in the plane and remains horizontal,
+// the y axis follows the steepest upward direction in the plane, x positive points to the right, and y positive points upslope.
 type PlanarDial struct {
 	Latitude                  float64
 	PlaneNormalAzimuth        float64
@@ -27,6 +33,9 @@ type PlanarDial struct {
 // X/Y 为影尖在盘面坐标系中的坐标；DenominatorQ 对应书中公式里的 Q；
 // SunAboveHorizon 表示太阳在地平线上方；PlaneIlluminated 表示盘面被太阳照亮；
 // Illuminated 为前两者同时满足。
+// X/Y are the shadow-tip coordinates in the dial-plane coordinate system. DenominatorQ is the Q term from the book formula.
+// SunAboveHorizon reports whether the Sun is above the horizon. PlaneIlluminated reports whether sunlight reaches the dial plane.
+// Illuminated is true only when both conditions are satisfied.
 type PlanarShadowPoint struct {
 	X                float64
 	Y                float64
@@ -41,6 +50,9 @@ type PlanarShadowPoint struct {
 // CenterX/CenterY 为日晷中心（极轴晷针固定点）坐标；PolarStylusLength 为极轴晷针长度；
 // PolarStylusPlaneAngle 为极轴晷针与盘面的夹角。HasFiniteCenter 为 false 时，
 // 表示极轴晷针与盘面平行，中心退化到无穷远处。
+// CenterX/CenterY are the coordinates of the dial center, where the polar stylus is fixed. PolarStylusLength is the polar-stylus length.
+// PolarStylusPlaneAngle is the angle between the polar stylus and the dial plane. When HasFiniteCenter is false,
+// the polar stylus is parallel to the plane and the center degenerates to infinity.
 type PlanarGeometry struct {
 	CenterX               float64
 	CenterY               float64
@@ -53,6 +65,8 @@ type PlanarGeometry struct {
 //
 // Start/End 均为有符号太阳时角，单位度，满足 Start <= End。
 // 约定取值范围为 [-180, 180]，用于表达一天中的一段连续时角。
+// Start and End are signed solar hour angles in degrees, with Start <= End.
+// The intended range is [-180, 180], representing one continuous hour-angle span within a day.
 type HourAngleInterval struct {
 	Start float64
 	End   float64
@@ -61,6 +75,7 @@ type HourAngleInterval struct {
 // DeclinationCurveSample 赤纬曲线采样点 / sampled point on a declination curve.
 //
 // HourAngle 为采样点的太阳时角；Point 为该时角下的影尖位置与照明状态。
+// HourAngle is the solar hour angle of the sample. Point gives the shadow-tip position and illumination state at that hour angle.
 type DeclinationCurveSample struct {
 	HourAngle float64
 	Point     PlanarShadowPoint
@@ -69,6 +84,7 @@ type DeclinationCurveSample struct {
 // DeclinationCurveSegment 赤纬曲线分段 / one illuminated segment of a declination curve.
 //
 // Interval 给出该段对应的连续受光时角范围；Samples 为该段内部的采样点。
+// Interval gives the continuous illuminated hour-angle span for the segment. Samples contains the sampled points within that segment.
 type DeclinationCurveSegment struct {
 	Declination float64
 	Interval    HourAngleInterval
@@ -80,6 +96,9 @@ type DeclinationCurveSegment struct {
 // Date 为该采样点对应的绝对时刻；其日期来自输入 date，钟面时间由调用参数指定。
 // Declination 为该采样瞬时的太阳赤纬；HourAngle 为换算后的视太阳时角；
 // Point 为该时角下的影尖位置与照明状态。
+// Date is the absolute instant of the sample. Its date comes from the input date, while the clock reading comes from the call parameters.
+// Declination is the solar declination at that instant. HourAngle is the derived apparent-solar hour angle.
+// Point gives the shadow-tip position and illumination state at that hour angle.
 type TimeLineSample struct {
 	Date        time.Time
 	Declination float64
@@ -90,6 +109,7 @@ type TimeLineSample struct {
 // EquatorialNorthDial 北面赤道日晷 / north-face equatorial dial.
 //
 // 北半球时用于春夏半年（太阳赤纬为正）；南半球也可直接按公式使用。
+// In the northern hemisphere this face is used during the spring and summer half-year, when solar declination is positive. The same formula can also be used directly in the southern hemisphere.
 func EquatorialNorthDial(latitude, stylusLength float64) PlanarDial {
 	return PlanarDial{
 		Latitude:                  latitude,
@@ -102,6 +122,7 @@ func EquatorialNorthDial(latitude, stylusLength float64) PlanarDial {
 // EquatorialSouthDial 南面赤道日晷 / south-face equatorial dial.
 //
 // 北半球时用于秋冬半年（太阳赤纬为负）；南半球也可直接按公式使用。
+// In the northern hemisphere this face is used during the autumn and winter half-year, when solar declination is negative. The same formula can also be used directly in the southern hemisphere.
 func EquatorialSouthDial(latitude, stylusLength float64) PlanarDial {
 	return PlanarDial{
 		Latitude:                  latitude,
@@ -114,6 +135,7 @@ func EquatorialSouthDial(latitude, stylusLength float64) PlanarDial {
 // HorizontalDial 水平日晷 / horizontal dial.
 //
 // 该构造器采用经典水平日晷的坐标约定：x 轴向东，y 轴向北。
+// This constructor follows the classical horizontal-dial coordinate convention: the x axis points east and the y axis points north.
 func HorizontalDial(latitude, stylusLength float64) PlanarDial {
 	return PlanarDial{
 		Latitude:                  latitude,
@@ -127,6 +149,8 @@ func HorizontalDial(latitude, stylusLength float64) PlanarDial {
 //
 // planeNormalAzimuth 为盘面法线方位角，按正北为 0°、向东增加。
 // 例如：朝南墙面取 180°，朝东墙面取 90°。
+// planeNormalAzimuth is the azimuth of the plane normal, measured from north toward east.
+// For example, use 180 degrees for a south-facing wall and 90 degrees for an east-facing wall.
 func VerticalDial(latitude, planeNormalAzimuth, stylusLength float64) PlanarDial {
 	return PlanarDial{
 		Latitude:                  latitude,
@@ -136,7 +160,10 @@ func VerticalDial(latitude, planeNormalAzimuth, stylusLength float64) PlanarDial
 	}
 }
 
-// Geometry 返回平面日晷的中心与极轴晷针几何量 / returns the derived planar geometry.
+// Geometry 平面日晷中心与极轴晷针几何量 / derived planar-dial center and polar-stylus geometry.
+//
+// 返回平面日晷的中心与极轴晷针几何量。
+// Returns the derived center and polar-stylus geometry of the planar dial.
 func (dial PlanarDial) Geometry() PlanarGeometry {
 	geometry := PlanarGeometry{
 		CenterX:               math.NaN(),
@@ -167,6 +194,7 @@ func (dial PlanarDial) Geometry() PlanarGeometry {
 // ShadowPointByHourAngleDeclination 影尖坐标（按时角与赤纬） / shadow point from hour angle and declination.
 //
 // hourAngle 为有符号太阳时角，上午为负，下午为正；declination 为太阳赤纬，单位度。
+// hourAngle is the signed solar hour angle, negative in the morning and positive in the afternoon. declination is solar declination in degrees.
 func (dial PlanarDial) ShadowPointByHourAngleDeclination(hourAngle, declination float64) PlanarShadowPoint {
 	point := PlanarShadowPoint{
 		X:            math.NaN(),
@@ -194,6 +222,7 @@ func (dial PlanarDial) ShadowPointByHourAngleDeclination(hourAngle, declination
 // ShadowPointAt 影尖坐标（按绝对时刻） / shadow point at an instant.
 //
 // 直接读取该时刻对应的视太阳时角和瞬时太阳赤纬，并返回平面日晷上的影尖位置。
+// Uses the apparent-solar hour angle and instantaneous solar declination at the supplied instant, and returns the shadow-tip position on the planar dial.
 func (dial PlanarDial) ShadowPointAt(date time.Time, lon float64) PlanarShadowPoint {
 	return dial.ShadowPointByHourAngleDeclination(HourAngle(date, lon), sun.ApparentDec(date))
 }
@@ -202,6 +231,8 @@ func (dial PlanarDial) ShadowPointAt(date time.Time, lon float64) PlanarShadowPo
 //
 // date 应处于目标地点的地方平太阳时区，例如 `MeanSolarTime` 的返回值；其原有钟面时间会被忽略。
 // meanSolarHours 为地方平太阳时钟面读数，单位小时，例如 9.5 表示 09:30。
+// date should already be expressed in the local mean-solar timezone of the site, for example a value returned by `MeanSolarTime`; its original clock fields are ignored.
+// meanSolarHours is the local mean-solar clock reading in hours, for example 9.5 for 09:30.
 func (dial PlanarDial) MeanSolarTimePoint(date time.Time, meanSolarHours float64) PlanarShadowPoint {
 	sampleTime := dateWithClockHours(date, meanSolarHours)
 	declination := sun.ApparentDec(sampleTime)
@@ -211,6 +242,7 @@ func (dial PlanarDial) MeanSolarTimePoint(date time.Time, meanSolarHours float64
 // ZoneTimePoint 区时影尖位置 / shadow point for zone time.
 //
 // date 提供民用日期和时区，原有钟面时间会被忽略；zoneTimeHours 为该时区下的区时钟面读数。
+// date provides the civil date and timezone; its original clock fields are ignored. zoneTimeHours is the civil clock reading in that timezone.
 func (dial PlanarDial) ZoneTimePoint(date time.Time, lon, zoneTimeHours float64) PlanarShadowPoint {
 	sampleTime := dateWithClockHours(date, zoneTimeHours)
 	declination := sun.ApparentDec(sampleTime)
@@ -221,6 +253,8 @@ func (dial PlanarDial) ZoneTimePoint(date time.Time, lon, zoneTimeHours float64)
 //
 // dates 由调用者自行决定取样日期密度，例如每月或每日；每个 date 都应处于目标地点的地方平太阳时区，
 // 例如先通过 `MeanSolarTime` 得到对应地点的地方平太阳时再取其年月日。meanSolarHours 为地方平太阳时钟面读数。
+// dates define the sampling cadence, for example monthly or daily. Each date should already be in the site's local mean-solar timezone,
+// for example by first calling `MeanSolarTime` and then keeping its year, month, and day. meanSolarHours is the local mean-solar clock reading.
 func (dial PlanarDial) MeanSolarTimeLine(dates []time.Time, meanSolarHours float64) []TimeLineSample {
 	if !isFinite(meanSolarHours) {
 		return nil
@@ -244,6 +278,8 @@ func (dial PlanarDial) MeanSolarTimeLine(dates []time.Time, meanSolarHours float
 //
 // dates 由调用者自行决定取样日期密度；zoneTimeHours 为 date 所在时区的区时钟面读数。
 // 每个 date 的原有钟面时间都会被 zoneTimeHours 替换。
+// dates define the sampling cadence. zoneTimeHours is the civil clock reading in the timezone carried by each date.
+// The original clock fields of every date are replaced by zoneTimeHours.
 func (dial PlanarDial) ZoneTimeLine(dates []time.Time, lon, zoneTimeHours float64) []TimeLineSample {
 	if !isFinite(zoneTimeHours) || !isFinite(lon) {
 		return nil
@@ -266,6 +302,7 @@ func (dial PlanarDial) ZoneTimeLine(dates []time.Time, lon, zoneTimeHours float6
 // PlaneIlluminatedHourAngleIntervals 盘面受光时角区间 / plane-illuminated hour-angle intervals.
 //
 // declination 为太阳赤纬，单位度。返回的区间只考虑盘面受光，不判断太阳是否在地平线上方。
+// declination is solar declination in degrees. The returned intervals consider only whether the dial plane is illuminated and do not test whether the Sun is above the horizon.
 func (dial PlanarDial) PlaneIlluminatedHourAngleIntervals(declination float64) []HourAngleInterval {
 	if !dial.isFinite() || !isFinite(declination) {
 		return nil
@@ -277,6 +314,7 @@ func (dial PlanarDial) PlaneIlluminatedHourAngleIntervals(declination float64) [
 // IlluminatedHourAngleIntervals 可见且受光时角区间 / illuminated hour-angle intervals.
 //
 // declination 为太阳赤纬，单位度。结果可直接用于日晷绘图时筛掉无效时线。
+// declination is solar declination in degrees. The result can be used directly to discard invalid hour-line segments in sundial plotting.
 func (dial PlanarDial) IlluminatedHourAngleIntervals(declination float64) []HourAngleInterval {
 	aboveHorizon := SunAboveHorizonHourAngleIntervals(dial.Latitude, declination)
 	planeLit := dial.PlaneIlluminatedHourAngleIntervals(declination)
@@ -287,6 +325,8 @@ func (dial PlanarDial) IlluminatedHourAngleIntervals(declination float64) []Hour
 //
 // declination 为太阳赤纬，单位度；hourAngleStep 为采样步长，单位度，常用值是 15°（每小时一格）。
 // 返回值按受光区间分段，每段都带有精确的时角范围；Samples 只包含区间内部的有效采样点。
+// declination is solar declination in degrees. hourAngleStep is the sampling step in degrees; 15 degrees is a common one-hour spacing.
+// The return value is split by illuminated intervals. Each segment carries the exact hour-angle bounds, and Samples contains only valid interior sample points.
 func (dial PlanarDial) DeclinationCurve(declination, hourAngleStep float64) []DeclinationCurveSegment {
 	if !dial.isFinite() || !isFinite(declination) || !isFinite(hourAngleStep) || hourAngleStep <= 0 {
 		return nil
@@ -315,6 +355,7 @@ func (dial PlanarDial) DeclinationCurve(declination, hourAngleStep float64) []De
 // DeclinationCurveAt 瞬时赤纬曲线采样 / declination-curve samples at an instant.
 //
 // 用 date 对应瞬时太阳赤纬生成日晷分段曲线采样。
+// Builds the segmented declination-curve samples from the instantaneous solar declination at date.
 func (dial PlanarDial) DeclinationCurveAt(date time.Time, hourAngleStep float64) []DeclinationCurveSegment {
 	return dial.DeclinationCurve(sun.ApparentDec(date), hourAngleStep)
 }
@@ -323,6 +364,7 @@ func (dial PlanarDial) DeclinationCurveAt(date time.Time, hourAngleStep float64)
 //
 // latitude 为地理纬度，declination 为太阳赤纬，单位度。结果只反映太阳是否升到地平线上方，
 // 不包含盘面朝向的影响。
+// latitude is geographic latitude and declination is solar declination, both in degrees. The result reflects only whether the Sun is above the horizon and does not include dial-plane orientation.
 func SunAboveHorizonHourAngleIntervals(latitude, declination float64) []HourAngleInterval {
 	if !isFinite(latitude) || !isFinite(declination) {
 		return nil

sundial/sundial.go

@@ -39,6 +39,9 @@ func HourAngle(date time.Time, lon float64) float64 {
 // date 负责提供地方平太阳时日期与时区，原有钟面时间会被 meanSolarHours 替换；
 // meanSolarHours 为地方平太阳时钟面读数，单位小时，例如 9.5 表示地方平太阳时 09:30。
 // 返回对应的视太阳时角，单位度，上午为负，下午为正。
+// date provides the local mean-solar date and timezone, while its clock fields are replaced by meanSolarHours.
+// meanSolarHours is the local mean-solar clock reading in hours, for example 9.5 for 09:30.
+// Returns the corresponding apparent-solar hour angle in degrees, negative in the morning and positive in the afternoon.
 func MeanSolarHourAngle(date time.Time, meanSolarHours float64) float64 {
 	if !isFinite(meanSolarHours) {
 		return math.NaN()
@@ -52,6 +55,9 @@ func MeanSolarHourAngle(date time.Time, meanSolarHours float64) float64 {
 // zoneTimeHours 为 date 所在时区下的钟面读数，单位小时；lon 为当地经度，东正西负。
 // 返回该区时在给定经度上对应的视太阳时角，单位度，上午为负，下午为正。
 // date 提供民用日期和时区；其原有钟面时间会被 zoneTimeHours 替换。
+// zoneTimeHours is the civil clock reading in the timezone carried by date, in hours; lon is east-positive longitude.
+// Returns the apparent-solar hour angle for that civil time and longitude, in degrees, negative in the morning and positive in the afternoon.
+// date provides the civil date and timezone, and its original clock fields are replaced by zoneTimeHours.
 func ZoneTimeHourAngle(date time.Time, lon, zoneTimeHours float64) float64 {
 	if !isFinite(zoneTimeHours) || !isFinite(lon) {
 		return math.NaN()
@@ -79,6 +85,7 @@ func HorizontalHourLineAngle(lat, hourAngle float64) float64 {
 // HorizontalHourLineAngleAt 水平日晷时线角 / horizontal sundial hour-line angle.
 //
 // 先按给定时刻和经度求瞬时视太阳时角，再结合纬度返回水平日晷的时线角。
+// First derives the apparent-solar hour angle for the supplied instant and longitude, then returns the horizontal-dial hour-line angle for the given latitude.
 func HorizontalHourLineAngleAt(date time.Time, lon, lat float64) float64 {
 	return HorizontalHourLineAngle(lat, HourAngle(date, lon))
 }

uranus/uranus.go

@@ -208,6 +208,7 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 // LastConjunction 上一次合日 / previous conjunction with the Sun.
 //
 // 返回 date 当前或之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastUranusConjunction(jde), date.Location(), false)
@@ -216,6 +217,7 @@ func LastConjunction(date time.Time) time.Time {
 // NextConjunction 下一次合日 / next conjunction with the Sun.
 //
 // 返回 date 当前或之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextUranusConjunction(jde), date.Location(), false)
@@ -224,6 +226,7 @@ func NextConjunction(date time.Time) time.Time {
 // LastOpposition 上一次冲日 / previous opposition.
 //
 // 返回 date 当前或之前最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or before date, keeping date's time zone.
 func LastOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastUranusOpposition(jde), date.Location(), false)
@@ -232,6 +235,7 @@ func LastOpposition(date time.Time) time.Time {
 // NextOpposition 下一次冲日 / next opposition.
 //
 // 返回 date 当前或之后最近一次冲日时刻，结果保持 date 的时区。
+// Returns the nearest opposition at or after date, keeping date's time zone.
 func NextOpposition(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextUranusOpposition(jde), date.Location(), false)
@@ -240,6 +244,7 @@ func NextOpposition(date time.Time) time.Time {
 // LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
 //
 // 返回 date 当前或之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastUranusProgradeToRetrograde(jde), date.Location(), false)
@@ -248,6 +253,7 @@ func LastProgradeToRetrograde(date time.Time) time.Time {
 // NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
 //
 // 返回 date 当前或之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextUranusProgradeToRetrograde(jde), date.Location(), false)
@@ -256,6 +262,7 @@ func NextProgradeToRetrograde(date time.Time) time.Time {
 // LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
 //
 // 返回 date 当前或之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastUranusRetrogradeToPrograde(jde), date.Location(), false)
@@ -264,6 +271,7 @@ func LastRetrogradeToPrograde(date time.Time) time.Time {
 // NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
 //
 // 返回 date 当前或之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextUranusRetrogradeToPrograde(jde), date.Location(), false)
@@ -272,6 +280,7 @@ func NextRetrogradeToPrograde(date time.Time) time.Time {
 // LastEasternQuadrature 上一次东方照 / previous eastern quadrature.
 //
 // 返回 date 当前或之前最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or before date, keeping date's time zone.
 func LastEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastUranusEasternQuadrature(jde), date.Location(), false)
@@ -280,6 +289,7 @@ func LastEasternQuadrature(date time.Time) time.Time {
 // NextEasternQuadrature 下一次东方照 / next eastern quadrature.
 //
 // 返回 date 当前或之后最近一次东方照时刻，结果保持 date 的时区。
+// Returns the nearest eastern quadrature at or after date, keeping date's time zone.
 func NextEasternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextUranusEasternQuadrature(jde), date.Location(), false)
@@ -288,6 +298,7 @@ func NextEasternQuadrature(date time.Time) time.Time {
 // LastWesternQuadrature 上一次西方照 / previous western quadrature.
 //
 // 返回 date 当前或之前最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or before date, keeping date's time zone.
 func LastWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastUranusWesternQuadrature(jde), date.Location(), false)
@@ -296,6 +307,7 @@ func LastWesternQuadrature(date time.Time) time.Time {
 // NextWesternQuadrature 下一次西方照 / next western quadrature.
 //
 // 返回 date 当前或之后最近一次西方照时刻，结果保持 date 的时区。
+// Returns the nearest western quadrature at or after date, keeping date's time zone.
 func NextWesternQuadrature(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextUranusWesternQuadrature(jde), date.Location(), false)

venus/venus.go

@@ -208,6 +208,7 @@ func SetTime(date time.Time, lon, lat, height float64, aero bool) (time.Time, er
 // LastConjunction 上一次合日 / previous conjunction with the Sun.
 //
 // 返回 date 当前或之前最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or before date, keeping date's time zone.
 func LastConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusConjunction(jde), date.Location(), false)
@@ -216,6 +217,7 @@ func LastConjunction(date time.Time) time.Time {
 // NextConjunction 下一次合日 / next conjunction with the Sun.
 //
 // 返回 date 当前或之后最近一次与太阳的合日时刻，结果保持 date 的时区。
+// Returns the nearest conjunction with the Sun at or after date, keeping date's time zone.
 func NextConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusConjunction(jde), date.Location(), false)
@@ -224,6 +226,7 @@ func NextConjunction(date time.Time) time.Time {
 // LastInferiorConjunction 上一次下合 / previous inferior conjunction.
 //
 // 返回 date 当前或之前最近一次下合时刻，结果保持 date 的时区。
+// Returns the nearest inferior conjunction at or before date, keeping date's time zone.
 func LastInferiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusInferiorConjunctionInclusive(jde), date.Location(), false)
@@ -232,6 +235,7 @@ func LastInferiorConjunction(date time.Time) time.Time {
 // NextInferiorConjunction 下一次下合 / next inferior conjunction.
 //
 // 返回 date 当前或之后最近一次下合时刻，结果保持 date 的时区。
+// Returns the nearest inferior conjunction at or after date, keeping date's time zone.
 func NextInferiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusInferiorConjunctionInclusive(jde), date.Location(), false)
@@ -240,6 +244,7 @@ func NextInferiorConjunction(date time.Time) time.Time {
 // LastSuperiorConjunction 上一次上合 / previous superior conjunction.
 //
 // 返回 date 当前或之前最近一次上合时刻，结果保持 date 的时区。
+// Returns the nearest superior conjunction at or before date, keeping date's time zone.
 func LastSuperiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusSuperiorConjunctionInclusive(jde), date.Location(), false)
@@ -248,6 +253,7 @@ func LastSuperiorConjunction(date time.Time) time.Time {
 // NextSuperiorConjunction 下一次上合 / next superior conjunction.
 //
 // 返回 date 当前或之后最近一次上合时刻，结果保持 date 的时区。
+// Returns the nearest superior conjunction at or after date, keeping date's time zone.
 func NextSuperiorConjunction(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusSuperiorConjunctionInclusive(jde), date.Location(), false)
@@ -256,6 +262,7 @@ func NextSuperiorConjunction(date time.Time) time.Time {
 // LastRetrograde 上一次留 / previous stationary point.
 //
 // 返回 date 当前或之前最近一次留时刻，不区分顺转逆还是逆转顺，结果保持 date 的时区。
+// Returns the nearest stationary point at or before date, regardless of the direction change, keeping date's time zone.
 func LastRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusRetrogradeInclusive(jde), date.Location(), false)
@@ -264,6 +271,7 @@ func LastRetrograde(date time.Time) time.Time {
 // NextRetrograde 下一次留 / next stationary point.
 //
 // 返回 date 当前或之后最近一次留时刻，不区分顺转逆还是逆转顺，结果保持 date 的时区。
+// Returns the nearest stationary point at or after date, regardless of the direction change, keeping date's time zone.
 func NextRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusRetrogradeInclusive(jde), date.Location(), false)
@@ -272,6 +280,7 @@ func NextRetrograde(date time.Time) time.Time {
 // LastProgradeToRetrograde 上一次顺行转逆行留 / previous station from prograde to retrograde.
 //
 // 返回 date 当前或之前最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from prograde to retrograde, keeping date's time zone.
 func LastProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusProgradeToRetrogradeInclusive(jde), date.Location(), false)
@@ -280,6 +289,7 @@ func LastProgradeToRetrograde(date time.Time) time.Time {
 // NextProgradeToRetrograde 下一次顺行转逆行留 / next station from prograde to retrograde.
 //
 // 返回 date 当前或之后最近一次由顺行转为逆行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from prograde to retrograde, keeping date's time zone.
 func NextProgradeToRetrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusProgradeToRetrogradeInclusive(jde), date.Location(), false)
@@ -288,6 +298,7 @@ func NextProgradeToRetrograde(date time.Time) time.Time {
 // LastRetrogradeToPrograde 上一次逆行转顺行留 / previous station from retrograde to prograde.
 //
 // 返回 date 当前或之前最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or before date where motion changes from retrograde to prograde, keeping date's time zone.
 func LastRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusRetrogradeToProgradeInclusive(jde), date.Location(), false)
@@ -296,6 +307,7 @@ func LastRetrogradeToPrograde(date time.Time) time.Time {
 // NextRetrogradeToPrograde 下一次逆行转顺行留 / next station from retrograde to prograde.
 //
 // 返回 date 当前或之后最近一次由逆行转为顺行的留时刻，结果保持 date 的时区。
+// Returns the nearest station at or after date where motion changes from retrograde to prograde, keeping date's time zone.
 func NextRetrogradeToPrograde(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusRetrogradeToProgradeInclusive(jde), date.Location(), false)
@@ -304,6 +316,7 @@ func NextRetrogradeToPrograde(date time.Time) time.Time {
 // LastGreatestElongation 上一次大距 / previous greatest elongation.
 //
 // 返回 date 当前或之前最近一次大距时刻，不区分东西大距，结果保持 date 的时区。
+// Returns the nearest greatest elongation at or before date, regardless of east or west, keeping date's time zone.
 func LastGreatestElongation(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusGreatestElongationInclusive(jde), date.Location(), false)
@@ -312,6 +325,7 @@ func LastGreatestElongation(date time.Time) time.Time {
 // NextGreatestElongation 下一次大距 / next greatest elongation.
 //
 // 返回 date 当前或之后最近一次大距时刻，不区分东西大距，结果保持 date 的时区。
+// Returns the nearest greatest elongation at or after date, regardless of east or west, keeping date's time zone.
 func NextGreatestElongation(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusGreatestElongationInclusive(jde), date.Location(), false)
@@ -320,6 +334,7 @@ func NextGreatestElongation(date time.Time) time.Time {
 // LastGreatestElongationEast 上一次东大距 / previous greatest eastern elongation.
 //
 // 返回 date 当前或之前最近一次东大距时刻，结果保持 date 的时区。
+// Returns the nearest eastern greatest elongation at or before date, keeping date's time zone.
 func LastGreatestElongationEast(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusGreatestElongationEastInclusive(jde), date.Location(), false)
@@ -328,6 +343,7 @@ func LastGreatestElongationEast(date time.Time) time.Time {
 // NextGreatestElongationEast 下一次东大距 / next greatest eastern elongation.
 //
 // 返回 date 当前或之后最近一次东大距时刻，结果保持 date 的时区。
+// Returns the nearest eastern greatest elongation at or after date, keeping date's time zone.
 func NextGreatestElongationEast(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusGreatestElongationEastInclusive(jde), date.Location(), false)
@@ -336,6 +352,7 @@ func NextGreatestElongationEast(date time.Time) time.Time {
 // LastGreatestElongationWest 上一次西大距 / previous greatest western elongation.
 //
 // 返回 date 当前或之前最近一次西大距时刻，结果保持 date 的时区。
+// Returns the nearest western greatest elongation at or before date, keeping date's time zone.
 func LastGreatestElongationWest(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.LastVenusGreatestElongationWestInclusive(jde), date.Location(), false)
@@ -344,6 +361,7 @@ func LastGreatestElongationWest(date time.Time) time.Time {
 // NextGreatestElongationWest 下一次西大距 / next greatest western elongation.
 //
 // 返回 date 当前或之后最近一次西大距时刻，结果保持 date 的时区。
+// Returns the nearest western greatest elongation at or after date, keeping date's time zone.
 func NextGreatestElongationWest(date time.Time) time.Time {
 	jde := basic.TD2UT(basic.Date2JDE(date.UTC()), true)
 	return basic.JDE2DateByZone(basic.NextVenusGreatestElongationWestInclusive(jde), date.Location(), false)