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

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

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)