b612/astro
1
1
Fork 0
Code Issues Pull Requests Projects Releases 18 Wiki Activity

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

Browse Source 
- 补齐公开接口说明段的英文描述，保持签名注释和详细说明均为中英双语结构
- 规范农历、坐标、公式、轨道、日晷、太阳、恒星及行星事件等 API 的注释口径
This commit is contained in:
兔子
2026-05-27 16:08:11 +08:00
parent 46b555cd49
commit c8dd777a7b
24 changed files with 310 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
calendar/chinese.go
+41
View File
@@ -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
+18
View File
@@ -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 {