#88337# docu review

6 files changed, 87 insertions, 46 deletions

diff --git a/sal/inc/osl/module.h b/sal/inc/osl/module.h
index 365daa998593..215b6bb1637a 100644
--- a/sal/inc/osl/module.h
+++ b/sal/inc/osl/module.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: module.h,v $
  *
- *  $Revision: 1.7 $
+ *  $Revision: 1.8 $
  *
- *  last change: $Author: hro $ $Date: 2001-09-03 10:47:34 $
+ *  last change: $Author: obr $ $Date: 2001-11-12 15:51:50 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -107,18 +107,18 @@ typedef void* oslModule;
 #endif
 
 
-/** Load a module.<BR>
+/** Load a shared library or module.
     @param strModuleName denotes the name of the module to be loaded.
-    @return 0 if the module could not be loaded, otherwise a handle to the module.
+    @return NULL if the module could not be loaded, otherwise a handle to the module.
 */
 oslModule SAL_CALL osl_loadModule(rtl_uString *strModuleName, sal_Int32 nRtldMode);
 
-/** Release the Module
+/** Release the module
 */
 void SAL_CALL osl_unloadModule(oslModule Module);
 
 /** lookup the specified symbolname.
-    @returns address of the symbol or 0 if lookup failed,
+    @return address of the symbol or NULL if lookup failed,
 */
 void* SAL_CALL osl_getSymbol(oslModule Module, rtl_uString *strSymbolName);
 
diff --git a/sal/inc/osl/module.hxx b/sal/inc/osl/module.hxx
index d10de776e582..b936da2a010d 100644
--- a/sal/inc/osl/module.hxx
+++ b/sal/inc/osl/module.hxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: module.hxx,v $
  *
- *  $Revision: 1.5 $
+ *  $Revision: 1.6 $
  *
- *  last change: $Author: kr $ $Date: 2001-09-03 11:08:37 $
+ *  last change: $Author: obr $ $Date: 2001-11-12 15:51:50 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -73,29 +73,51 @@
 namespace osl
 {
 
+/** A class representing a share library module
+*/
 class Module
 {
     Module( const Module&);
     Module& operator = ( const Module&);
 
 public:
+    /** Lookup URL of module which is mapped at the specified address.
+        @param  addr specifies an address in the process memory space
+        @param  pustrURL receives the URL of the module that is mapped at pv
+        @return sal_True on success, sal_False if no module can be found at the specified address
+    */
     static sal_Bool getUrlFromAddress(void * addr, ::rtl::OUString & libraryUrl) {
         return osl_getModuleURLFromAddress(addr, &libraryUrl.pData);
     }
 
 
+    /** Constructs an uninitialized module object.
+    */
     Module(): m_Module(0){}
 
+    /** Contructs the module object and loads the shared library or module.
+        @param strModuleName the module to load
+        @seealso ::osl_loadModule()
+    */
     Module( const ::rtl::OUString& strModuleName, sal_Int32 nRtldMode = SAL_LOADMODULE_DEFAULT)
     {
         load( strModuleName, nRtldMode);
     }
 
+    /** Unloads the module and destructs the object
+        @seealso ::osl_unloadModule()
+    */
     ~Module()
     {
         osl_unloadModule(m_Module);
     }
 
+    /** Loads the shared library or module.
+
+        A previously loaded module will be unloaded before the new one gets loaded.
+        @param strModuleName the module to load
+        @seealso ::osl_loadModule()
+    */
     sal_Bool SAL_CALL load( const ::rtl::OUString& strModuleName,
         sal_Int32 nRtldMode = SAL_LOADMODULE_DEFAULT)
     {
@@ -104,6 +126,9 @@ public:
         return is();
     }
 
+    /** Unloads the module.
+        @seealso ::osl_unloadModule()
+    */
     void SAL_CALL unload()
     {
         if (m_Module)
@@ -113,16 +138,27 @@ public:
         }
     }
 
+    /** Checks if a module is loaded.
+        @return sal_True if the module is loaded, sal_False if not
+    */
     sal_Bool SAL_CALL is() const
     {
            return m_Module != NULL;
     }
 
+    /** Extract a symbol from the module.
+        @param strSymbolName the symbol to extract.
+        @return the address of the symbol
+        @seealso ::osl_getSymbol()
+    */
     void* SAL_CALL getSymbol( const ::rtl::OUString& strSymbolName)
     {
         return ( osl_getSymbol( m_Module, strSymbolName.pData ) );
     }
 
+    /** Cast operator to oslModule.
+        @return the oslModule handle
+    */
     operator oslModule() const
     {
         return m_Module;
diff --git a/sal/inc/osl/nlsupport.h b/sal/inc/osl/nlsupport.h
index a351f9ca6ae6..fa75f9a2c87d 100644
--- a/sal/inc/osl/nlsupport.h
+++ b/sal/inc/osl/nlsupport.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: nlsupport.h,v $
  *
- *  $Revision: 1.2 $
+ *  $Revision: 1.3 $
  *
- *  last change: $Author: jsc $ $Date: 2001-04-26 08:22:27 $
+ *  last change: $Author: obr $ $Date: 2001-11-12 15:51:50 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -75,15 +75,14 @@
 extern "C" {
 #endif
 
-/**
-    Determines the text encoding used by the underlying platform for the
+/** Determines the text encoding used by the underlying platform for the
     specified locale.
 
     @param pLocale
     the locale to return the text encoding for. If this parameter is NULL,
     the default locale of the current process is used.
 
-    @returns the rtl_TextEncoding that matches the platform specific encoding
+    @return the rtl_TextEncoding that matches the platform specific encoding
     description or RTL_TEXTENCODING_DONTKNOW if no mapping is available.
 */
 
diff --git a/sal/inc/osl/semaphor.h b/sal/inc/osl/semaphor.h
index efecd834a7ea..40d75d4af0b9 100644
--- a/sal/inc/osl/semaphor.h
+++ b/sal/inc/osl/semaphor.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: semaphor.h,v $
  *
- *  $Revision: 1.6 $
+ *  $Revision: 1.7 $
  *
- *  last change: $Author: jl $ $Date: 2001-03-19 09:36:56 $
+ *  last change: $Author: obr $ $Date: 2001-11-12 15:51:50 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -72,34 +72,36 @@ extern "C" {
 
 typedef void* oslSemaphore;
 
-/** Creates a semaphore.<BR>
+/** Creates a semaphore.
     @param InitialCount denotes the starting value the semaphore. If you set it to
     zero, the first acquire() blocks. Otherwise InitialCount acquire()s  are
     immedeatly  successfull.
-    @return 0 if the semaphore could not be created, otherwise a handle to the sem.
+    @return NULL if the semaphore could not be created, otherwise a handle
+    to the created semaphore object.
 */
 oslSemaphore SAL_CALL osl_createSemaphore(sal_uInt32 initialCount);
 
-/** Release the OS-structures and free semaphore data-structure
-    @return fbbb
+/** Release the OS-structures and free semaphore data-structure.
 */
 void SAL_CALL osl_destroySemaphore(oslSemaphore Semaphore);
 
-/** acquire() decreases the count. It will block if it tries to
-    decrease below zero.
-    @return False if the system-call failed.
+/** Decrease the count of a semaphore.
+
+    It will block if it tries to decrease below zero.
+    @return sal_False if the system-call failed.
 */
 sal_Bool SAL_CALL osl_acquireSemaphore(oslSemaphore Semaphore);
 
-/** tryToAcquire() tries to decreases the count. It will
-    return with False if it would decrease the count below zero.
-    (When acquire() would block.) If it could successfully
-    decrease the count, it will return True.
+/** tries to decreases the count of a semaphore.
+
+    @return sal_False if it would decrease the count below zero.
+    (acquire() would block). If it could successfully
+    decrease the count, it will return sal_True.
 */
 sal_Bool SAL_CALL osl_tryToAcquireSemaphore(oslSemaphore Semaphore);
 
-/** release() increases the count.
-    @return False if the system-call failed.
+/** Increases the count of a semaphore.
+    @return sal_False if the system-call failed.
 */
 sal_Bool SAL_CALL osl_releaseSemaphore(oslSemaphore Semaphore);
 
diff --git a/sal/inc/osl/semaphor.hxx b/sal/inc/osl/semaphor.hxx
index 7b2e00a0d622..8e0b14e47957 100644
--- a/sal/inc/osl/semaphor.hxx
+++ b/sal/inc/osl/semaphor.hxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: semaphor.hxx,v $
  *
- *  $Revision: 1.4 $
+ *  $Revision: 1.5 $
  *
- *  last change: $Author: jl $ $Date: 2001-03-14 08:30:26 $
+ *  last change: $Author: obr $ $Date: 2001-11-12 15:51:50 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -75,11 +75,11 @@ namespace osl
 
     public:
 
-        /** Creates a semaphore.<BR>
+        /** Creates a semaphore.
             @param InitialCount denotes the starting value the semaphore. If you set it to
             zero, the first acquire() blocks. Otherwise InitialCount acquire()s  are
             immedeatly  successfull.
-            @return 0 if the semaphore could not be created, otherwise a handle to the sem.
+            @seealso ::osl_createSemaphore()
         */
 
         Semaphore(sal_uInt32 initialCount)
@@ -88,34 +88,39 @@ namespace osl
         }
 
         /** Release the OS-structures and free semaphore data-structure
-            @return fbbb
+            @seealso ::osl_destroySemaphore()
         */
         ~Semaphore()
         {
             osl_destroySemaphore(semaphore);
         }
 
-        /** acquire() decreases the count. It will block if it tries to
-            decrease below zero.
-            @return False if the system-call failed.
+        /** Decreases the count of the semaphore object.
+
+            It will block if it tries to decrease below zero.
+            @return sal_False if the system-call failed
+            @seealso ::osl_acquireSemaphore()
         */
         sal_Bool acquire()
         {
             return osl_acquireSemaphore(semaphore);
         }
 
-        /** tryToAcquire() tries to decreases the count. It will
-            return with False if it would decrease the count below zero.
-            (When acquire() would block.) If it could successfully
-            decrease the count, it will return True.
+        /** Tries to decreases the count of the semaphore.
+
+            @return sal_False if it would decrease the count below zero
+            (acquire() would block). If it could successfully
+            decrease the count, it will return sal_True.
+            @seealso ::osl_tryToAcquireSemaphore()
         */
         sal_Bool tryToAcquire()
         {
             return osl_tryToAcquireSemaphore(semaphore);
         }
 
-        /** release() increases the count.
-            @return False if the system-call failed.
+        /** Increases the count.
+            @return sal_False if the system-call failed.
+            @seealso ::osl_releaseSemaphore()
         */
         sal_Bool release()
         {
diff --git a/sal/inc/osl/util.h b/sal/inc/osl/util.h
index fbfd429f68db..2f56fd6e6f4d 100644
--- a/sal/inc/osl/util.h
+++ b/sal/inc/osl/util.h
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: util.h,v $
  *
- *  $Revision: 1.3 $
+ *  $Revision: 1.4 $
  *
- *  last change: $Author: jsc $ $Date: 2001-04-26 08:22:27 $
+ *  last change: $Author: obr $ $Date: 2001-11-12 15:51:50 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -69,9 +69,8 @@
 extern "C" {
 #endif
 
-/**
+/** Retrieves an ethernet address of the machine.
     @param pEthernetAddr 6 bytes of memory
-
     @return sal_True  if the ethernetaddress could be retrieved. <br>
             sal_False if no address could be found. This may be either because
            there is no ethernet card or there is no appropriate algorithm