#88337# docu reviewed

3 files changed, 147 insertions, 100 deletions

diff --git a/bridges/inc/bridges/remote/connection.h b/bridges/inc/bridges/remote/connection.h
index 32806c58e909..5c5f540a9f8a 100644
--- a/bridges/inc/bridges/remote/connection.h
+++ b/bridges/inc/bridges/remote/connection.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: connection.h,v $
  *
- *  $Revision: 1.1.1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: hr $ $Date: 2000-09-18 15:28:47 $
+ *  last change: $Author: jbu $ $Date: 2001-11-05 11:41:09 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -62,37 +62,39 @@
 #define _BRIDGES_REMOTE_CONNECTION_H_
 #include <sal/types.h>
 
+/** Specfies a C-interface for a bidirectional bytestream,
+    which is used by a UNO remote environment.
+ */
 struct remote_Connection
 {
     void ( SAL_CALL * acquire ) ( remote_Connection *);
 
     void ( SAL_CALL * release ) ( remote_Connection *);
 
+    /**
+      reads nSize bytes from the connection. This method blocks, until
+      all bytes are available or an error occurs.
+      @return Number of bytes read.
+              If the return value is less than nSize, an unrecoverable
+              i/o error has occured or the connection was closed.
 
-    /***
-     * reads nSize bytes from the connection. This method blocks, until
-     * all bytes are available or an error occurs.
-     * @return Number of bytes read.<br>
-     *         If the return value is less than nSize, an unrecoverable
-     *         i/o error has occured or the connection was closed.
-     *
-     ***/
+     */
     sal_Int32 (SAL_CALL * read)(remote_Connection *, sal_Int8 *pDest, sal_Int32 nSize );
 
-    /***
-     * @return Number of bytes written.<br>
-     *         if the return value is less than nSize an unrecoverable
-     *         i/o error has occured or the connection was closed.
-     ***/
+    /**
+      @return Number of bytes written.
+              if the return value is less than nSize an unrecoverable
+              i/o error has occured or the connection was closed.
+     */
     sal_Int32 (SAL_CALL * write)(remote_Connection *, const sal_Int8 *pSource, sal_Int32 nSize );
 
     void ( SAL_CALL * flush ) ( remote_Connection * );
 
-    /***
-     * closes the connection. Any read or write operation after this call shall not be served
-     * anymore. Any ongoing read or write operation must return immeadiatly after this call.
-     * The implementation should cope with multiple calls to this method.
-     ***/
+    /** closes the connection.
+        Any read or write operation after this call shall not be served
+        anymore. Any ongoing read or write operation must return immeadiatly after this call.
+        The implementation should cope with multiple calls to this method.
+     */
     void (SAL_CALL * close) ( remote_Connection * );
 };
 
diff --git a/bridges/inc/bridges/remote/context.h b/bridges/inc/bridges/remote/context.h
index 137d036fad83..dd5ceba5fd05 100644
--- a/bridges/inc/bridges/remote/context.h
+++ b/bridges/inc/bridges/remote/context.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: context.h,v $
  *
- *  $Revision: 1.3 $
+ *  $Revision: 1.4 $
  *
- *  last change: $Author: jbu $ $Date: 2001-05-02 13:56:30 $
+ *  last change: $Author: jbu $ $Date: 2001-11-05 11:41:09 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -69,12 +69,30 @@
 #include <uno/environment.h>
 #include <uno/any2.h>
 
+
+/** Interface for refcounted contexts of uno-environments.
+
+    Not all uno_Contexts need to be refcounted, in case they are,
+    they should be 'derived' from this struct.
+    This is used as a base class for the remote_Context.
+    @see uno_Environment
+    @see uno_getEnvironment()
+    @see remote_Context
+ */
 struct uno_Context
 {
+    /** increase the refcount of the context
+     */
     void (SAL_CALL * acquire)( uno_Context *pContext );
 
+    /** decrements the recount of the context. In case the recount drops to zero,
+        the context gets destroye.
+    */
     void (SAL_CALL * release)( uno_Context *pContext);
 
+    /** Allows to query for a different interface of the uno_Context.
+        The result of the void pointer is unspecified and depends on the concrete context.
+     */
     void * (SAL_CALL *query ) ( uno_Context *pContext , rtl_uString *pId);
 };
 
@@ -84,12 +102,11 @@ struct remote_Interface;
 
 
 
-/***
- * performs a query-interface for a certain interface via the remote connection !
- *
- * @param pEnvRemote The environment, that shall perform the call.
- * @param ppRemoteI  in/out parameter contains the interface returned by queryInterface
- * @param pOid       the oid of the 'ghost' object on which the call must be done.
+/** performs a query-interface for a certain interface via the remote connection !
+
+  @param pEnvRemote The environment, that shall perform the call.
+  @param ppRemoteI  in/out parameter contains the interface returned by queryInterface
+  @param pOid       the oid of the 'ghost' object on which the call must be done.
  ***/
 typedef void ( SAL_CALL * remote_getInstanceFunc ) (
     uno_Environment *pEnvRemote,
@@ -98,6 +115,9 @@ typedef void ( SAL_CALL * remote_getInstanceFunc ) (
     typelib_TypeDescriptionReference *pInterfaceTypeRef,
     uno_Any **ppException );
 
+
+/** refcounted C-interface, which provides object by name.
+ */
 struct remote_InstanceProvider
 {
     void (SAL_CALL * acquire ) ( remote_InstanceProvider * pProvider );
@@ -110,6 +130,11 @@ struct remote_InstanceProvider
                                      uno_Any **ppException );
 };
 
+/** refcounted C-interface, which allows to register a listener to an
+    remote bridge to be informed when the bridge gets disposed.
+
+   @see remote_Context
+ */
 struct remote_DisposingListener
 {
     void (SAL_CALL * acquire     ) ( remote_DisposingListener * pProvider );
@@ -120,31 +145,35 @@ struct remote_DisposingListener
 
 
 /**
- * Try to get an existing context characterized by the IDString. Each ID-String must
- * uniquely charcterize a certain connection.
- *
- * @return 0 when such a context does not exist, otherwise
- *         a pointer to an acquired uno remote context
+  Try to get an existing context characterized by the pIdString. Each ID-String must
+  uniquely charcterize a certain connection. The context can't be retrieved via this
+  function anymore, after it got disposed.
+
+  @return 0 when such a context does not exist, otherwise
+          a pointer to an acquired remote_Context.
  **/
 extern "C" SAL_DLLEXPORT remote_Context * SAL_CALL
 remote_getContext( rtl_uString *pIdString );
 
 /**
- * Create an acquired remote context. The Context is weakly held by the context administration
- * and can be accessed later through getRemoteContext() (using the same id-string).
- *
- * @param pIdString A string, that uniquely describes the connection. For e.g. a socket connection,
- *                  host and port of the local and remote host should be in the string.
- *
- * @param pDescription
- *                  Description of the connection, that may brought up to the user.
- *
- * @param pProtocol
- *                  The protocol, that the environment uses for
- *                  communicating with the remote process.
- *                  The format of the protocol string is : "protocolname,para1=para1value,..."
- * @return 0, when a context with this name already exists.
- **/
+  Create an acquired remote context. The Context is weakly held by the context administration
+  and can be accessed later through remote_getContext() (using the same id-string).
+
+  @param pIdString A string, that uniquely describes the connection. For e.g. a socket connection,
+                   host and port of the local and remote host should be in the string.
+
+  @param pDescription
+                   Description of the connection, that may brought up to the user.
+
+  @param pProtocol
+                   The protocol, that the environment uses for
+                   communicating with the remote process.
+                   The format of the protocol string is : "protocolname,para1=para1value,..."
+  @return 0, when a context with this name already exists.
+
+  @see remote_getContext()
+  @see remote_Context
+ */
 extern "C" SAL_DLLEXPORT remote_Context * SAL_CALL
 remote_createContext( remote_Connection *pConnection,
                       rtl_uString *pIdStr,
@@ -162,21 +191,27 @@ typedef void ( SAL_CALL * remote_contextListenerFunc ) (
     rtl_uString *sDescription
     );
 
-
+/** Registers a listener at the context administration, which allows to keep
+    track of existing remote connections.
+    @param pObject object which is handed to the listener function, when called.
+ */
 extern "C" SAL_DLLEXPORT void SAL_CALL
 remote_addContextListener( remote_contextListenerFunc listener, void *pObject );
 
+
+/** Removes a listener from the context administration.
+ */
 extern "C" SAL_DLLEXPORT void SAL_CALL
 remote_removeContextListener( remote_contextListenerFunc listener , void *pObject );
 
-/****
- * @param pnStringCount out parameter. Contains the number of rtl_uStrings in the array
- * @param memAlloc      a memory allocation function for the array of  pointers to rtl_uStrings
- *
- * @return array of rtl strings. The caller must call release on all rtl_uString s and must free
- *         the pointer array.
- *
- ***/
+/** Allows to retrieve all existing context strings.
+
+   @param pnStringCount out parameter. Contains the number of rtl_uStrings in the array
+   @param memAlloc      a memory allocation function for the array of  pointers to rtl_uStrings
+
+   @return array of rtl strings. The caller must call release on all rtl_uString s and must free
+           the pointer array.
+ */
 extern "C" SAL_DLLEXPORT rtl_uString ** SAL_CALL
 remote_getContextList(
     sal_Int32 *pnStringCount,
@@ -185,71 +220,73 @@ remote_getContextList(
 
 struct remote_BridgeImpl;
 
+/** The context structure for a remote bridge.
+
+    @see uno_getEnvironment()
+ */
 struct remote_Context
 {
     struct uno_Context aBase;
 
-    /***
-     * These methods are implemented by context administration
-     ***/
+    /**
+       These methods are implemented by context administration
+     */
     void ( SAL_CALL * addDisposingListener ) ( remote_Context *,
                                                remote_DisposingListener * );
     void ( SAL_CALL * removeDisposingListener ) ( remote_Context *,
                                                   remote_DisposingListener * );
-    /***
-     * will be called by the environment when it gets disposed
-     ***/
+    /**
+       will be called by the environment when it gets disposed
+     */
     void ( SAL_CALL * dispose ) ( remote_Context * );
 
-    /********
-     * see above declaration of remote_getInstanceFunc
-     * The method is set by the environment during environment initialization.
-     *******/
+    /** The method is set by the remote-environment during environment initialization.
+      @see remote_getInstanceFunc
+     */
     remote_getInstanceFunc getRemoteInstance;
 
-    /*******
-     * The protocol, that the environment uses for communicating with the remote process.
-     * The format of the protocol string is : "protocolname,para1=para1value,..."
-     * The parameters are protocol dependend
-     ******/
+    /**
+      The protocol, that the environment uses for communicating with the remote process.
+      The format of the protocol string is : "protocolname,para1=para1value,..."
+      The parameters are protocol dependend
+     */
     rtl_uString *m_pProtocol;
 
-    /****
-     * It may be the same as m_pName.
-     * Livetime is handled by the context administration.
-     ****/
+    /**
+       It may be the same as m_pName.
+       Livetime is handled by the context administration.
+     */
     rtl_uString *m_pDescription;
 
-    /****
-     * The name of this context at context administration.
-     * A string, that uniquely describes this environment.
-     * Livetime is handled by the context administration.
-     ****/
+    /**
+      The name of this context at context administration.
+      A string, that uniquely describes this environment.
+      Livetime is handled by the context administration.
+     */
     rtl_uString *m_pName;
 
-    /**
-     * GetInstance method is called every time when a remote call with an unknown oid comes in.
-     * Is usually called on server side,  when the first client request comes in.
-     * Maybe 0. Livetime is handled by the context administration.
-     ***/
+    /** The instance-provider, which is used to look up unknown object identifiers.
+      Is usually called on server side,  when the first client request comes in.
+      Maybe 0. Livetime is handled by the context administration.
+     */
     remote_InstanceProvider *m_pInstanceProvider;
 
-    /***
-     * The connection of this context.
-     * Livetime is handled by the context administration.
-     ***/
+    /**
+       The connection of this context.
+       Livetime is handled by the context administration.
+     */
     remote_Connection *m_pConnection;
 
     /**
-     * Here arbitrary data may be stored. It may be used by a connection
-     * service to store environment specific data. The bridge does not
-     * use it.
-     **/
+      Here arbitrary data may be stored. It may be used by a connection
+      service to store environment specific data. The bridge does not
+      use it.
+     */
     void *m_pAdditionalInformation;
 
     /**
-     * here the bridge stores its private per environment data.
-     **/
+      here the bridge stores its private per environment data.
+     */
     struct remote_BridgeImpl *m_pBridgeImpl;
 };
 
diff --git a/bridges/inc/bridges/remote/remote.h b/bridges/inc/bridges/remote/remote.h
index 0f5c23b34592..ed8ff6169fae 100644
--- a/bridges/inc/bridges/remote/remote.h
+++ b/bridges/inc/bridges/remote/remote.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: remote.h,v $
  *
- *  $Revision: 1.3 $
+ *  $Revision: 1.4 $
  *
- *  last change: $Author: kz $ $Date: 2001-04-18 11:09:36 $
+ *  last change: $Author: jbu $ $Date: 2001-11-05 11:41:09 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -84,13 +84,17 @@
 
 struct remote_Interface;
 
+/** @internal
+ */
 typedef void (SAL_CALL * remote_DispatchMethod)( remote_Interface * pRemoteI,
                                                  typelib_TypeDescription * pMemberType,
                                                  void * pReturn,
                                                  void * pArgs[],
                                                  uno_Any ** ppException );
 
-
+/**
+   @internal
+ */
 typedef void ( SAL_CALL * requestClientSideDispatcher ) (
     uno_Environment *pEnvRemote,
     typelib_TypeDescription * pMemberType,
@@ -100,6 +104,8 @@ typedef void ( SAL_CALL * requestClientSideDispatcher ) (
     void *ppArgs[],
     uno_Any **ppException );
 
+/** The base class of an UNO interface in a remote environment.
+ */
 struct remote_Interface
 {
     void (SAL_CALL * acquire)( remote_Interface * pInterface );
@@ -109,7 +115,9 @@ struct remote_Interface
     remote_DispatchMethod pDispatcher;
 };
 
-
+/** The mapping between an binary-c-uno and a remote environment.
+    @internal
+ */
 struct remote_Mapping
 {
     uno_Mapping aBase;