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

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

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 等