MediaClient: Update comments to last changes

* The interface is being refined and various comments were inconsistent
at this point.
* AddInput/AddOutput is private now.

headers/private/media/MediaClient.h

@@ -26,10 +26,10 @@ class BMediaOutput;
 
 // BMediaClient is a general purpose class allowing to create any kind
 // of media_node. It automatically manage the expected behavior under
-// different run modes, and allow to specify the different capabilities
-// which you may want. It work with a central loop allowing to handle,
-// calling the right callbacks automatically events at a certain
-// performance_time.
+// different run modes, and allow to specify the different capabilities needed.
+// BMediaClient is not using any of the coding patterns you might be used to.
+// There are no events to care, and threading is managed internally using
+// the data processing specified by the BMediaGraph class.
 class BMediaClient {
 public:
 									BMediaClient(const char* name,
@@ -53,11 +53,9 @@ public:
 	// TODO: Add file interface
 	// TODO: Offline mode is still missing
 
-	// To connect pass the BMediaConnection to this class or to another BMediaClient,
-	// also in another team the connection object will be valid.
 	// When those functions return, the BMediaConnection is added to the
-	// list and is visible to other nodes as not connected.
-
+	// list and is visible to other nodes as not connected. Any input/output
+	// should be registered to a BMediaNode to become something useful.
 	virtual status_t				RegisterInput(BMediaInput* input);
 	virtual status_t				RegisterOutput(BMediaOutput* output);
 
@@ -106,6 +104,10 @@ public:
 
 			bool					IsRunning() const;
 
+	// NOTE: The following functions aren't provided to be inherited,
+	// always use the protected HandleSomething version. This is because
+	// otherwise you could break the connection mechanism and mine interoperability
+	// from remote nodes.
 			status_t				Start(bool force = false);
 			status_t				Stop(bool force = false);
 			status_t				Seek(bigtime_t mediaTime,
@@ -143,12 +145,6 @@ public:
 	virtual	BMediaAddOn*			AddOn(int32* id) const;
 
 protected:
-	// This is used when the user want to override the BeginConnection
-	// mechanism, for example to supply your BMediaConnection derived
-	// class. Take ownership of the object.
-	virtual void					AddInput(BMediaInput* input);
-	virtual void					AddOutput(BMediaOutput* output);
-
 	virtual void					HandleStart(bigtime_t performanceTime);
 	virtual void					HandleStop(bigtime_t performanceTime);
 
@@ -166,6 +162,9 @@ protected:
 			status_t				ConnectionReleased(BMediaConnection* conn);
 
 private:
+	virtual void					AddInput(BMediaInput* input);
+	virtual void					AddOutput(BMediaOutput* output);
+
 			BMediaInput*			FindInput(
 										const media_destination& dest) const;
 			BMediaOutput*			FindOutput(

headers/private/media/MediaConnection.h

@@ -22,12 +22,9 @@ namespace BPrivate { namespace media {
 // It represents a connection between two nodes and allow to create complex
 // nodes without dealing with the unneeded complexity. Two local connections,
 // can be binded, this means that when you will receive a buffer A as input,
-// the Process function will be called so that you can process the BBuffer,
+// the BufferReceived function will be called so that you can process the BBuffer,
 // and once the function returns the output will be automatically forwarded
-// to the connection B.
-// If you don't bind a connection, you have to call yourself the
-// BMediaClient::SendBuffer() method or call BMediaClient::Recycle to
-// recycle the buffer when you don't want to do anything further.
+// to the connection B SendBuffer method.
 class BMediaConnection {
 public:
 	virtual							~BMediaConnection();
@@ -165,10 +162,11 @@ protected:
 	virtual status_t				FormatProposal(media_format* format);
 	virtual status_t				FormatChangeRequested(media_format* format);
 
-	// When a connection is not binded with another, it's your job to send
-	// the buffer to the connection you want. You might want
-	// to ovverride it so that you can track something, in this case
-	// be sure to call the base version.
+	// When a connection is not binded with another, and you really don't want
+	// to use BMediaGraph it's your job to send the buffer to the connection
+	// you want. You might want to ovverride it so that you can track something,
+	// in this case be sure to call the base version. Be sure to know what
+	// you are doing.
 	virtual	status_t				SendBuffer(BBuffer* buffer);
 
 private: