Fixed obsolete comments in stream.h and session.h about stream transmitting media immediately

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@414 74dad513-b988-da41-8d7b-12977e46ad98

2 files changed, 36 insertions, 8 deletions

diff --git a/pjmedia/include/pjmedia/session.h b/pjmedia/include/pjmedia/session.h
index 762f9b8d..cfc1bf8e 100644
--- a/pjmedia/include/pjmedia/session.h
+++ b/pjmedia/include/pjmedia/session.h
@@ -88,9 +88,15 @@ PJ_DECL(pj_status_t) pjmedia_stream_info_from_sdp(
 
 
 /**
- * Create media session based on the local and remote SDP.
- * The session will start immediately.
- *
+ * Create media session based on the local and remote SDP. After the session
+ * has been created, application normally would want to get the media port 
+ * interface of each streams, by calling #pjmedia_session_get_port(). The 
+ * media port interface exports put_frame() and get_frame() function, used
+ * to transmit and receive media frames from the stream.
+ *
+ * Without application calling put_frame() and get_frame(), there will be 
+ * no media frames transmitted or received by the session.
+ * 
  * @param endpt		The PJMEDIA endpoint instance.
  * @param stream_cnt	Maximum number of streams to be created. This
  *			also denotes the number of elements in the
@@ -118,7 +124,7 @@ pjmedia_session_create( pjmedia_endpt *endpt,
 
 
 /**
- * Get session info.
+ * Get media session info of the session.
  *
  * @param session	The session which info is being queried.
  * @param info		Pointer to receive session info.
@@ -131,6 +137,8 @@ PJ_DECL(pj_status_t) pjmedia_session_get_info( pjmedia_session *session,
 
 /**
  * Activate all streams in media session for the specified direction.
+ * Application only needs to call this function if it previously paused
+ * the session.
  *
  * @param session	The media session.
  * @param dir		The direction to activate.
@@ -198,7 +206,17 @@ pjmedia_session_enum_streams( const pjmedia_session *session,
 
 
 /**
- * Get the port interface for the specified stream.
+ * Get the media port interface of the specified stream. The media port
+ * interface declares put_frame() and get_frame() function, which is the 
+ * only  way for application to transmit and receive media frames from the
+ * stream.
+ *
+ * @param session	The media session.
+ * @param index		Stream index.
+ * @param p_port	Pointer to receive the media port interface for
+ *			the specified stream.
+ *
+ * @return		PJ_SUCCESS on success.
  */
 PJ_DECL(pj_status_t) pjmedia_session_get_port( pjmedia_session *session,
 					       unsigned index,
diff --git a/pjmedia/include/pjmedia/stream.h b/pjmedia/include/pjmedia/stream.h
index 90d2a2f6..05007dc4 100644
--- a/pjmedia/include/pjmedia/stream.h
+++ b/pjmedia/include/pjmedia/stream.h
@@ -83,8 +83,14 @@ struct pjmedia_stream_info
 
 
 /**
- * Create a media stream based on the specified stream parameter.
- * All channels in the stream initially will be inactive.
+ * Create a media stream based on the specified parameter. After the stream
+ * has been created, application normally would want to get the media port 
+ * interface of the streams, by calling pjmedia_stream_get_port(). The 
+ * media port interface exports put_frame() and get_frame() function, used
+ * to transmit and receive media frames from the stream.
+ *
+ * Without application calling put_frame() and get_frame(), there will be 
+ * no media frames transmitted or received by the stream.
  *
  * @param endpt		Media endpoint.
  * @param pool		Pool to allocate memory for the stream. A large
@@ -111,8 +117,12 @@ PJ_DECL(pj_status_t) pjmedia_stream_create(pjmedia_endpt *endpt,
  */
 PJ_DECL(pj_status_t) pjmedia_stream_destroy(pjmedia_stream *stream);
 
+
 /**
- * Get the port interface of the stream.
+ * Get the media port interface of the stream. The media port interface
+ * declares put_frame() and get_frame() function, which is the only 
+ * way for application to transmit and receive media frames from the
+ * stream.
  *
  * @param stream	The media stream.
  * @param p_port	Pointer to receive the port interface.