add a bit of comments on internal functions.

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@76458 65c4cc65-6c06-0410-ace0-fbb531ad65f3

channels/chan_sip.c

@@ -1094,7 +1094,12 @@ static void dialoglist_unlock(void)
 	ast_mutex_unlock(&dialoglock);
 }
 
-/*! \brief sip packet - raw format for outbound packets that are sent or scheduled for transmission */
+/*! \brief sip packet - raw format for outbound packets that are sent or scheduled for transmission
+ * Packets are linked in a list, whose head is in the struct sip_pvt they belong to.
+ * Each packet holds a reference to the parent struct sip_pvt.
+ * This structure is allocated in __sip_reliable_xmit() and only for packets that
+ * require retransmissions.
+ */
 struct sip_pkt {
 	struct sip_pkt *next;			/*!< Next packet in linked list */
 	int retrans;				/*!< Retransmission number */
@@ -4729,7 +4734,10 @@ static void make_our_tag(char *tagbuf, size_t len)
 	snprintf(tagbuf, len, "as%08lx", ast_random());
 }
 
-/*! \brief Allocate SIP_PVT structure and set defaults */
+/*! \brief Allocate sip_pvt structure, set defaults and link in the container.
+ * Returns a reference to the object so whoever uses it later must
+ * remember to release the reference.
+ */
 static struct sip_pvt *sip_alloc(ast_string_field callid, struct sockaddr_in *sin,
 				 int useglobal_nat, const int intended_method)
 {
@@ -4862,8 +4870,11 @@ static struct sip_pvt *sip_alloc(ast_string_field callid, struct sockaddr_in *si
 	return p;
 }
 
-/*! \brief Connect incoming SIP message to current dialog or create new dialog structure
-	Called by handle_request, sipsock_read */
+/*! \brief find or create a dialog structure for an incoming SIP message.
+ * Connect incoming SIP message to current dialog or create new dialog structure
+ * Returns a reference to the sip_pvt object, remember to give it back once done.
+ *     Called by handle_request, sipsock_read
+ */
 static struct sip_pvt *find_call(struct sip_request *req, struct sockaddr_in *sin, const int intended_method)
 {
 	struct sip_pvt *p = NULL;
@@ -4973,7 +4984,7 @@ static struct sip_pvt *find_call(struct sip_request *req, struct sockaddr_in *si
 				ast_debug(4, "Failed allocating SIP dialog, sending 500 Server internal error and giving up\n");
 			}
 		}
-		return p;
+		return p; /* can be NULL */
 	} else if( sip_methods[intended_method].can_create == CAN_CREATE_DIALOG_UNSUPPORTED_METHOD) {
 		/* A method we do not support, let's take it on the volley */
 		transmit_response_using_temp(callid, sin, 1, intended_method, req, "501 Method Not Implemented");
@@ -5065,7 +5076,7 @@ static int sip_register(char *value, int lineno)
 	reg->callid_valid = FALSE;
 	reg->ocseq = INITIAL_CSEQ;
 	ASTOBJ_CONTAINER_LINK(&regl, reg);	/* Add the new registry entry to the list */
-	registry_unref(reg);
+	registry_unref(reg);	/* release the reference given by ASTOBJ_INIT. The container has another reference */
 	return 0;
 }
 
@@ -7821,7 +7832,12 @@ static char *regstate2str(enum sipregistrystate regstate)
 	}
 }
 
-/*! \brief Update registration with SIP Proxy */
+/*! \brief Update registration with SIP Proxy.
+ * Called from the scheduler when the previous registration expires,
+ * so we don't have to cancel the pending event.
+ * We assume the reference so the sip_registry is valid, since it
+ * is stored in the scheduled event anyways.
+ */
 static int sip_reregister(void *data) 
 {
 	/* if we are here, we know that we need to reregister. */
@@ -7853,7 +7869,12 @@ static int __sip_do_register(struct sip_registry *r)
 	return res;
 }
 
-/*! \brief Registration timeout, register again */
+/*! \brief Registration timeout, register again
+ * Registered as a timeout handler during transmit_register(),
+ * to retransmit the packet if a reply does not come back.
+ * This is called by the scheduler so the event is not pending anymore when
+ * we are called.
+ */
 static int sip_reg_timeout(void *data)
 {
 
@@ -7867,6 +7888,10 @@ static int sip_reg_timeout(void *data)
 		return 0;
 
 	ast_log(LOG_NOTICE, "   -- Registration for '%s@%s' timed out, trying again (Attempt #%d)\n", r->username, r->hostname, r->regattempts); 
+	/* If the initial tranmission failed, we may not have an existing dialog,
+	 * so it is possible that r->call == NULL.
+	 * Otherwise destroy it, as we have a timeout so we don't want it.
+	 */
 	if (r->call) {
 		/* Unlink us, destroy old call.  Locking is not relevant here because all this happens
 		   in the single SIP manager thread. */
@@ -7897,7 +7922,9 @@ static int sip_reg_timeout(void *data)
 	return 0;
 }
 
-/*! \brief Transmit register to SIP proxy or UA */
+/*! \brief Transmit register to SIP proxy or UA
+ * auth = NULL on the initial registration (from sip_reregister())
+ */
 static int transmit_register(struct sip_registry *r, int sipmethod, const char *auth, const char *authheader)
 {
 	struct sip_request req;
@@ -9226,6 +9253,9 @@ static int get_rdnis(struct sip_pvt *p, struct sip_request *oreq)
 
 /*! \brief Find out who the call is for 
 	We use the INVITE uri to find out
+	\return 0 on success (found a matching extension),
+	1 for pickup extension or overlap dialling support (if we support it),
+	-1 on error.
 */
 static int get_destination(struct sip_pvt *p, struct sip_request *oreq)
 {
@@ -9338,6 +9368,7 @@ static int get_destination(struct sip_pvt *p, struct sip_request *oreq)
 	- Their tag is fromtag, our tag is to-tag
 	- This means that in some transactions, totag needs to be their tag :-)
 	  depending upon the direction
+	Returns a reference, remember to release it when done XXX
 */
 static struct sip_pvt *get_sip_pvt_byid_locked(const char *callid, const char *totag, const char *fromtag) 
 {