From 35936c1f0170c72bfc604f6904f76d45306931d9 Mon Sep 17 00:00:00 2001
From: Dave Collins <davec@conformal.com>
Date: Thu, 27 Mar 2014 14:05:27 -0500
Subject: [PATCH] Don't discuss internals in exported func comments.

This commit cleans up and moves a couple of comments in the recent pull
request which implements a rebroadcast handler (#114) in order to avoid
discussing internal state in the exported function comment.

How a function actually accomplishes the stated functionality is not
something that a caller is concerned with.  The details about the internal
state are better handled with comments inside the function body.
---
 server.go | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/server.go b/server.go
index 5358c892..0f2ef834 100644
--- a/server.go
+++ b/server.go
@@ -97,11 +97,13 @@ type peerState struct {
 }
 
 // randomUint16Number returns a random uint16 in a specified input range.  Note
-// that the range is in zeroth ordering; if you pass it 1800, you will get values
-// from 0 to 1800.  In order to avoid modulo bias and ensure every possible
-// outcome in [0, max) has equal probability, the random number must be sampled
-// from a random source that has a range limited to a multiple of the modulus.
+// that the range is in zeroth ordering; if you pass it 1800, you will get
+// values from 0 to 1800.
 func randomUint16Number(max uint16) uint16 {
+	// In order to avoid modulo bias and ensure every possible outcome in
+	// [0, max) has equal probability, the random number must be sampled
+	// from a random source that has a range limited to a multiple of the
+	// modulus.
 	var randomNumber uint16
 	var limitRange = (math.MaxUint16 / max) * max
 	for {
@@ -112,14 +114,14 @@ func randomUint16Number(max uint16) uint16 {
 	}
 }
 
-// AddRebroadcastInventory dispatches a message to the rebroadcastHandler
-// specifying to add an item to the rebroadcast map of InvVects
+// AddRebroadcastInventory adds 'iv' to the list of inventories to be
+// rebroadcasted at random intervals until they show up in a block.
 func (s *server) AddRebroadcastInventory(iv *btcwire.InvVect) {
 	s.modifyRebroadcastInv <- broadcastInventoryAdd(iv)
 }
 
-// RemoveRebroadcastInventory dispatches a message to the rebroadcastHandler
-// specifying to remove an item from the rebroadcast map of InvVects
+// RemoveRebroadcastInventory removes 'iv' from the list of items to be
+// rebroadcasted if present.
 func (s *server) RemoveRebroadcastInventory(iv *btcwire.InvVect) {
 	s.modifyRebroadcastInv <- broadcastInventoryDel(iv)
 }