From 8e2fe9febef80ccc2b6fcda4fa5750b554d5de4b Mon Sep 17 00:00:00 2001
From: Emil Ivov <emcho@jitsi.org>
Date: Wed, 11 Nov 2009 05:42:20 +0000
Subject: [PATCH] Adds javadocs to media handler

---
 .../protocol/sip/CallPeerMediaHandler.java    | 34 +++++++++++++++----
 .../impl/protocol/sip/CallPeerSipImpl.java    |  3 +-
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/src/net/java/sip/communicator/impl/protocol/sip/CallPeerMediaHandler.java b/src/net/java/sip/communicator/impl/protocol/sip/CallPeerMediaHandler.java
index e142095ce..1c52c84cd 100644
--- a/src/net/java/sip/communicator/impl/protocol/sip/CallPeerMediaHandler.java
+++ b/src/net/java/sip/communicator/impl/protocol/sip/CallPeerMediaHandler.java
@@ -643,13 +643,25 @@ private void registerDynamicPTsWithStream(MediaStream stream)
     /**
      * Parses <tt>offerString</tt>, creates the <tt>MediaStream</tt>s that it
      * describes and constructs a response representing the state of this
-     * <tt>MediaHandler</tt>.
-     * @param offerString
-     * @return
-     * @throws OperationFailedException
+     * <tt>MediaHandler</tt>. The method takes into account the presence or
+     * absence of previous negotiations and interprets the <tt>offerString</tt>
+     * as an initial offer or a session update accordingly.
+     *
+     * @param offerString The SDP offer that we'd like to parse, handle and get
+     * a response for.
+     *
+     * @return A <tt>String</tt> containing the SDP response representing the
+     * current state of this <tt>MediaHandler</tt>.
+     *
+     * @throws OperationFailedException if parsing or handling
+     * <tt>offerString</tt> fails or we have a problem while creating the
+     * response.
+     * @throws IllegalArgumentException if there's a problem with the format
+     * or semantings of the <tt>offerString</tt>.
      */
     public String processOffer(String offerString)
-        throws OperationFailedException
+        throws OperationFailedException,
+               IllegalArgumentException
     {
         SessionDescription offer = SdpUtils.parseSdpString(offerString);
         if (localSess == null)
@@ -658,7 +670,17 @@ public String processOffer(String offerString)
             return processUpdateOffer(offer, localSess).toString();
     }
 
-    public SessionDescription processFirstOffer(SessionDescription offer)
+    /**
+     * Parses and handles the specified <tt>SessionDescription offer</tt> and
+     * returns and SDP answer representing the current state of this media
+     * handler.
+     *
+     * @param offer
+     * @return
+     * @throws OperationFailedException
+     * @throws IllegalArgumentException
+     */
+    private SessionDescription processFirstOffer(SessionDescription offer)
         throws OperationFailedException,
                IllegalArgumentException
     {
diff --git a/src/net/java/sip/communicator/impl/protocol/sip/CallPeerSipImpl.java b/src/net/java/sip/communicator/impl/protocol/sip/CallPeerSipImpl.java
index 98c9711dc..b462c6467 100644
--- a/src/net/java/sip/communicator/impl/protocol/sip/CallPeerSipImpl.java
+++ b/src/net/java/sip/communicator/impl/protocol/sip/CallPeerSipImpl.java
@@ -1136,8 +1136,7 @@ public synchronized void answer()
             // if the offer was in the invite create an sdp answer
             if ((sdpOffer != null) && (sdpOffer.length() > 0))
             {
-                sdp = getMediaHandler().processFirstOffer(
-                                SdpUtils.parseSdpString(sdpOffer)).toString();
+                sdp = getMediaHandler().processOffer(sdpOffer);
             }
             // if there was no offer in the invite - create an offer
             else