docs(contract): refine public docs after #1161

contract/r/gnoswap/community_pool/community_pool.gno

@@ -17,7 +17,8 @@ import (
 // Parameters:
 //   - tokenPath: the path to the token contract (e.g., "gno.land/r/gnoswap/gns")
 //
-// Returns the balance of the specified token held by the community pool.
+// Returns:
+//   - balance: the balance of the specified token held by the community pool
 func GetBalanceOf(tokenPath string) int64 {
 	communityPoolAddr := access.MustGetAddress(prbac.ROLE_COMMUNITY_POOL.String())
 

contract/r/gnoswap/emission/distribution.gno

@@ -219,6 +219,12 @@ func transferToTarget(targets map[address]int64) error {
 }
 
 // GetDistributionBpsPct returns the distribution percentage in basis points for a specific target.
+//
+// Parameters:
+//   - target: distribution target identifier
+//
+// Returns:
+//   - percentage: distribution percentage in basis points
 func GetDistributionBpsPct(target int) int64 {
 	assertValidDistributionTarget(target)
 	if distributionBpsPct == nil {
@@ -237,25 +243,44 @@ func GetDistributionBpsPct(target int) int64 {
 }
 
 // GetDistributedToStaker returns pending GNS for liquidity stakers.
+//
+// Returns:
+//   - amount: pending GNS amount for stakers
 func GetDistributedToStaker() int64 {
 	return distributedToStaker
 }
 
 // GetDistributedToDevOps returns accumulated GNS for DevOps.
+//
+// Returns:
+//   - amount: pending GNS amount for DevOps
 func GetDistributedToDevOps() int64 {
 	return distributedToDevOps
 }
 
 // GetDistributedToCommunityPool returns the amount of GNS distributed to Community Pool.
+//
+// Returns:
+//   - amount: pending GNS amount for Community Pool
 func GetDistributedToCommunityPool() int64 {
 	return distributedToCommunityPool
 }
 
 // GetDistributedToGovStaker returns the amount of GNS distributed to governance stakers since last clear.
+//
+// Returns:
+//   - amount: pending GNS amount for governance stakers
 func GetDistributedToGovStaker() int64 {
 	return distributedToGovStaker
 }
 
+// AccumulateDistributedInfo returns pending distribution amounts for all targets.
+//
+// Returns:
+//   - toStaker: pending GNS for liquidity stakers
+//   - toDevOps: pending GNS for DevOps
+//   - toCommunityPool: pending GNS for Community Pool
+//   - toGovStaker: pending GNS for governance stakers
 func AccumulateDistributedInfo() (toStaker, toDevOps, toCommunityPool, toGovStaker int64) {
 	toStaker = GetDistributedToStaker()
 	toDevOps = GetDistributedToDevOps()
@@ -265,37 +290,67 @@ func AccumulateDistributedInfo() (toStaker, toDevOps, toCommunityPool, toGovStak
 }
 
 // GetAccuDistributedToStaker returns the total historical GNS distributed to liquidity stakers.
+//
+// Returns:
+//   - amount: total historical GNS distributed to stakers
 func GetAccuDistributedToStaker() int64 {
 	return accuDistributedToStaker
 }
 
 // GetAccuDistributedToDevOps returns the total historical GNS distributed to DevOps.
+//
+// Returns:
+//   - amount: total historical GNS distributed to DevOps
 func GetAccuDistributedToDevOps() int64 {
 	return accuDistributedToDevOps
 }
 
 // GetAccuDistributedToCommunityPool returns the total historical GNS distributed to Community Pool.
+//
+// Returns:
+//   - amount: total historical GNS distributed to Community Pool
 func GetAccuDistributedToCommunityPool() int64 {
 	return accuDistributedToCommunityPool
 }
 
 // GetAccuDistributedToGovStaker returns the total historical GNS distributed to governance stakers.
+//
+// Returns:
+//   - amount: total historical GNS distributed to governance stakers
 func GetAccuDistributedToGovStaker() int64 {
 	return accuDistributedToGovStaker
 }
 
 // GetEmissionAmountPerSecondBy returns the emission amount per second for a given timestamp and distribution percentage.
+//
+// Parameters:
+//   - timestamp: timestamp to calculate emission for
+//   - distributionPct: distribution percentage in basis points
+//
+// Returns:
+//   - amount: emission amount per second
 func GetEmissionAmountPerSecondBy(timestamp, distributionPct int64) int64 {
 	return calculateAmount(gns.GetEmissionAmountPerSecondByTimestamp(timestamp), distributionPct)
 }
 
 // GetStakerEmissionAmountPerSecond returns the current per-second emission amount allocated to liquidity stakers.
+//
+// Returns:
+//   - amount: emission amount per second for stakers
 func GetStakerEmissionAmountPerSecond() int64 {
 	currentTimestamp := time.Now().Unix()
 	return GetEmissionAmountPerSecondBy(currentTimestamp, GetDistributionBpsPct(LIQUIDITY_STAKER))
 }
 
 // GetStakerEmissionAmountPerSecondInRange returns emission amounts allocated to liquidity stakers for a time range.
+//
+// Parameters:
+//   - start: start timestamp
+//   - end: end timestamp
+//
+// Returns:
+//   - halvingBlocks: halving block timestamps
+//   - halvingEmissions: emission amounts at each halving
 func GetStakerEmissionAmountPerSecondInRange(start, end int64) ([]int64, []int64) {
 	halvingBlocks, halvingEmissions := gns.GetEmissionAmountPerSecondInRange(start, end)
 	for i := range halvingBlocks {

contract/r/gnoswap/emission/emission.gno

@@ -57,7 +57,8 @@ func setLastExecutedTimestamp(timestamp int64) {
 // last distribution and distributes them to predefined targets (staker, devops, etc.).
 //
 // Returns:
-//   - int64: Total amount of GNS distributed in this call
+//   - distributedAmount: total amount of GNS distributed in this call
+//   - success: true if distribution was attempted
 //
 // Note: Distribution only occurs if start timestamp is set and reached.
 // Any undistributed tokens from previous calls are carried forward.
@@ -212,6 +213,9 @@ func SetDistributionStartTime(cur realm, startTimestamp int64) {
 // SetOnDistributionPctChangeCallback sets a callback function to be called when distribution percentages change.
 // This allows external contracts (like staker) to update their internal caches when governance changes emission rates.
 //
+// Parameters:
+//   - callback: function to call with emission amount per second when percentages change
+//
 // Only callable by the staker contract.
 func SetOnDistributionPctChangeCallback(cur realm, callback func(int64)) {
 	caller := runtime.PreviousRealm().Address()

contract/r/gnoswap/emission/getter.gno

@@ -1,22 +1,33 @@
 package emission
 
 // GetLeftGNSAmount returns the amount of undistributed GNS tokens from previous distributions.
+//
+// Returns:
+//   - amount: undistributed GNS amount
 func GetLeftGNSAmount() int64 {
 	return leftGNSAmount
 }
 
 // GetDistributionStartTimestamp returns the timestamp when emission distribution started.
-// Returns 0 if distribution has not been started yet.
+//
+// Returns:
+//   - timestamp: distribution start timestamp, or 0 if not started
 func GetDistributionStartTimestamp() int64 {
 	return distributionStartTimestamp
 }
 
 // GetLastExecutedTimestamp returns the timestamp of the last emission distribution execution.
+//
+// Returns:
+//   - timestamp: last execution timestamp
 func GetLastExecutedTimestamp() int64 {
 	return lastExecutedTimestamp
 }
 
 // GetAllDistributionBpsPct returns all distribution percentages in basis points.
+//
+// Returns:
+//   - percentages: map of target to percentage in basis points
 func GetAllDistributionBpsPct() map[int]int64 {
 	result := make(map[int]int64, len(distributionBpsPct))
 	if distributionBpsPct == nil {
@@ -31,6 +42,9 @@ func GetAllDistributionBpsPct() map[int]int64 {
 }
 
 // GetTotalAccuDistributed returns the total accumulated distributed GNS amount.
+//
+// Returns:
+//   - amount: total accumulated distributed GNS
 func GetTotalAccuDistributed() int64 {
 	return safeAddInt64(
 		safeAddInt64(accuDistributedToStaker, accuDistributedToDevOps),
@@ -39,6 +53,9 @@ func GetTotalAccuDistributed() int64 {
 }
 
 // GetTotalDistributed returns the total pending distributed GNS amount.
+//
+// Returns:
+//   - amount: total pending distributed GNS
 func GetTotalDistributed() int64 {
 	return safeAddInt64(
 		safeAddInt64(distributedToStaker, distributedToDevOps),
@@ -47,7 +64,9 @@ func GetTotalDistributed() int64 {
 }
 
 // GetDistributionEndTimestamp returns the timestamp when emission distribution ends.
-// Returns 0 if distribution has not been started yet.
+//
+// Returns:
+//   - timestamp: distribution end timestamp, or 0 if not started
 func GetDistributionEndTimestamp() int64 {
 	if distributionStartTimestamp == 0 {
 		return 0
@@ -58,6 +77,14 @@ func GetDistributionEndTimestamp() int64 {
 
 // GetDistributableAmount returns distribution amounts by target and the remainder.
 // If timestamp is outside the distribution window, it returns an empty map and the full amount as left.
+//
+// Parameters:
+//   - amount: total amount to distribute
+//   - timestamp: timestamp to check distribution window
+//
+// Returns:
+//   - distributions: map of target to distribution amount
+//   - remainder: undistributed amount
 func GetDistributableAmount(amount, timestamp int64) (map[int]int64, int64) {
 	if distributionStartTimestamp == 0 || timestamp < distributionStartTimestamp {
 		return make(map[int]int64), amount

contract/r/gnoswap/gns/emission.gno

@@ -9,8 +9,13 @@ import (
 )
 
 // InitEmissionState initializes emission schedule with start timestamp.
-// Only callable by emission contract. Sets up 12-year emission schedule
-// with halving every 2 years. Panics if caller is not emission contract.
+// Sets up 12-year emission schedule with halving every 2 years.
+//
+// Parameters:
+//   - height: block height when emission starts
+//   - timestamp: timestamp when emission starts
+//
+// Only callable by emission contract. Panics if caller is not emission contract.
 func InitEmissionState(cur realm, createdHeight int64, startTimestamp int64) {
 	previousRealm := runtime.PreviousRealm()
 	caller := previousRealm.Address()