#88337# Minor documentation improvements.

1 files changed, 53 insertions, 29 deletions

diff --git a/salhelper/inc/salhelper/simplereferenceobject.hxx b/salhelper/inc/salhelper/simplereferenceobject.hxx
index 0cbb303b8736..a40b0cc63cbb 100755
--- a/salhelper/inc/salhelper/simplereferenceobject.hxx
+++ b/salhelper/inc/salhelper/simplereferenceobject.hxx
@@ -2,9 +2,9 @@
  *
  *  $RCSfile: simplereferenceobject.hxx,v $
  *
- *  $Revision: 1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: sb $ $Date: 2001-06-05 15:20:37 $
+ *  last change: $Author: sb $ $Date: 2001-10-29 12:42:54 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -80,6 +80,32 @@
 
 namespace salhelper {
 
+/** A simple base implementation for reference-counted objects.
+
+    Classes that want to implement a reference-counting mechanism based on the
+    acquire()/release() interface should derive from this class.
+
+    The reason to have class local operators new and delete here is technical.
+    Imagine a class D derived from SimpleReferenceObject, but implemented in
+    another shared library that happens to use different global operators new
+    and delete from those used in this shared library (which, sadly, seems to
+    be possible with shared libraries).  Now, without the class local
+    operators new and delete here, a code sequence like "new D" would use the
+    global operator new as found in the other shared library, while the code
+    sequence "delete this" in release() would use the global operator delete
+    as found in this shared library---and these two operators would not be
+    guaranteed to match.
+
+    There are no overloaded operators new and delete for placement new here,
+    because it is felt that the concept of placement new does not work well
+    with the concept of reference-counted objects; so it seems best to simply
+    leave those operators out.
+
+    The same problem as with operators new and delete would also be there with
+    operators new[] and delete[].  But since arrays of reference-counted
+    objects are of no use, anyway, it seems best to simply declare and not
+    define (private) operators new[] and delete[].
+ */
 class SimpleReferenceObject
 {
 public:
@@ -97,38 +123,22 @@ public:
     inline void release() SAL_THROW(())
     { if (osl_decrementInterlockedCount(&m_nCount) == 0) delete this; }
 
-    /** @descr
-        The reason to have class local operators new and delete here is
-        technical.  Imagine a class D derived from SimpleReferenceObject, but
-        implemented in another shared library that happens to use different
-        global operators new and delete from those used in this shared library
-        (which, sadly, seems to be possible with shared libraries...).  Now,
-        without the class local operators new and delete here, a code sequence
-        like "new D" would use the global operator new as found in the other
-        shared library, while the code sequence "delete this" in release()
-        would use the global operator delete as found in this shared library
-        ---and these two operators would not be guaranteed to match.
-
-        @descr
-        There are no overloaded operators new and delete for placement new
-        here, because it is felt that the concept of placement new does not
-        work well with the concept of a reference counted object; so it seems
-        best to simply leave those operators out.
-
-        @descr
-        The same problem as with operators new and delete would also be there
-        with operators new[] and delete[].  But since arrays of reference
-        counted objects are of no use, anyway, it seems best to simply declare
-        and not define (private) operators new[] and delete[].
+    /** see general class documentation
      */
     static void * operator new(std::size_t nSize) SAL_THROW((std::bad_alloc));
 
+    /** see general class documentation
+     */
     static void * operator new(std::size_t nSize,
                                std::nothrow_t const & rNothrow)
         SAL_THROW(());
 
+    /** see general class documentation
+     */
     static void operator delete(void * pPtr) SAL_THROW(());
 
+    /** see general class documentation
+     */
     static void operator delete(void * pPtr, std::nothrow_t const & rNothrow)
         SAL_THROW(());
 
@@ -138,11 +148,25 @@ protected:
 private:
     oslInterlockedCount m_nCount;
 
-    SimpleReferenceObject(SimpleReferenceObject &); // not implemented
-    void operator =(SimpleReferenceObject); // not implemented
+    /** not implemented
+        @internal
+     */
+    SimpleReferenceObject(SimpleReferenceObject &);
 
-    static void * operator new[](std::size_t); // not implemented
-    static void operator delete[](void * pPtr); // not implemented
+    /** not implemented
+        @internal
+     */
+    void operator =(SimpleReferenceObject);
+
+    /** not implemented (see general class documentation)
+        @internal
+     */
+    static void * operator new[](std::size_t);
+
+    /** not implemented (see general class documentation)
+        @internal
+     */
+    static void operator delete[](void * pPtr);
 };
 
 }