Doxygen topic overview cleanups.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52088 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/doxygen/mainpages/topics.h

@@ -37,7 +37,7 @@
 
  @li @subpage overview_backwardcompat
  @li @subpage overview_runtimeclass
- @li @subpage overview_trefcount
+ @li @subpage overview_refcount
  @li @subpage overview_app
  @li @subpage overview_unicode
  @li @subpage overview_mbconvclasses
@@ -63,7 +63,7 @@
  @li @subpage overview_thread
  @li @subpage overview_config
  @li @subpage overview_fs
- @li @subpage overview_resyn
+ @li @subpage overview_resyntax
  @li @subpage overview_arc
  @li @subpage overview_ipc
 

docs/doxygen/overviews/refcount.h

@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        trefcount
+// Name:        refcount.h
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
@@ -8,114 +8,117 @@
 
 /*!
 
- @page trefcount_overview Reference counting
+@page overview_refcount Reference Counting
 
- @ref refcount_overview
+@li @ref overview_refcount_ignore
- @ref refcountequality_overview
+@li @ref overview_refcount_equality
- @ref refcountdestruct_overview
+@li @ref overview_refcount_destruct
- @ref refcountlist_overview
+@li @ref overview_refcount_list
- @ref object_overview
+@li @ref overview_refcount_object
 
 
- @section refcount Why you shouldn't care about it
+<hr>
-
- Many wxWidgets objects use a technique known as @e reference counting, also known
- as @e copy on write (COW).
- This means that when an object is assigned to another, no copying really takes place:
- only the reference count on the shared object data is incremented and both objects
- share the same data (a very fast operation).
- But as soon as one of the two (or more) objects is modified, the data has to be
- copied because the changes to one of the objects shouldn't be seen in the
- others. As data copying only happens when the object is written to, this is
- known as COW.
- What is important to understand is that all this happens absolutely
- transparently to the class users and that whether an object is shared or not
- is not seen from the outside of the class - in any case, the result of any
- operation on it is the same.
-
- @section refcountequality Object comparison
-
- The == and != operators of @ref refcountlist_overview
- always do a @c deep comparison.
- This means that the equality operator will return @true if two objects are
- identic and not only if they share the same data.
- Note that wxWidgets follows the @e STL philosophy: when a comparison operator cannot
- be implemented efficiently (like for e.g. wxImage's == operator which would need to
- compare pixel-by-pixel the entire image's data), it's not implemented at all.
- That's why not all reference-counted wxWidgets classes provide comparison operators.
- Also note that if you only need to do a @c shallow comparison between two
- #wxObject-derived classes, you should not use the == and != operators
- but rather the wxObject::IsSameAs function.
 
 
- @section refcountdestruct Object destruction
+@section overview_refcount_ignore Why You Shouldn't Care About It
 
- When a COW object destructor is called, it may not delete the data: if it's shared,
+Many wxWidgets objects use a technique known as <em>reference counting</em>,
- the destructor will just decrement the shared data's reference count without destroying it.
+also known as <em>copy on write</em> (COW). This means that when an object is
- Only when the destructor of the last object owning the data is called, the data is really
+assigned to another, no copying really takes place. Only the reference count on
- destroyed. As for all other COW-things, this happens transparently to the class users so
+the shared object data is incremented and both objects share the same data (a
- that you shouldn't care about it.
+very fast operation).
+
+But as soon as one of the two (or more) objects is modified, the data has to be
+copied because the changes to one of the objects shouldn't be seen in the
+others. As data copying only happens when the object is written to, this is
+known as COW.
+
+What is important to understand is that all this happens absolutely
+transparently to the class users and that whether an object is shared or not is
+not seen from the outside of the class - in any case, the result of any
+operation on it is the same.
 
 
- @section refcountlist List of reference-counted wxWidgets classes
+@section overview_refcount_equality Object Comparison
 
- The following classes in wxWidgets have efficient (i.e. fast) assignment operators
+The == and != operators of the reference counted classes always do a @c deep
- and copy constructors since they are reference-counted:
+comparison. This means that the equality operator will return @true if two
- #wxAcceleratorTable
+objects are identical and not only if they share the same data.
 
- #wxAnimation
+Note that wxWidgets follows the <em>STL philosophy</em>: when a comparison
+operator can not be implemented efficiently (like for e.g. wxImage's ==
+operator which would need to compare the entire image's data, pixel-by-pixel),
+it's not implemented at all. That's why not all reference counted classes
+provide comparison operators.
 
- #wxBitmap
+Also note that if you only need to do a @c shallow comparison between two
-
+#wxObject derived classes, you should not use the == and != operators but
- #wxBrush
+rather the wxObject::IsSameAs function.
-
- #wxCursor
-
- #wxFont
-
- #wxIcon
-
- #wxImage
-
- #wxMetafile
-
- #wxPalette
-
- #wxPen
-
- #wxRegion
-
- #wxString
-
- #wxVariant
-
- #wxVariantData
- Note that the list above reports the objects which are reference-counted in all ports of
- wxWidgets; some ports may use this tecnique also for other classes.
-
- @section wxobjectoverview Make your own reference-counted class
-
- Reference counting can be implemented easily using #wxObject
- and #wxObjectRefData classes. Alternatively, you
- can also use the #wxObjectDataPtrT template.
- First, derive a new class from #wxObjectRefData and
- put there the memory-consuming data.
- Then derive a new class from #wxObject and implement there
- the public interface which will be seen by the user of your class.
- You'll probably want to add a function to your class which does the cast from
- #wxObjectRefData to your class-specific shared data; e.g.:
-
- @code
- MyClassRefData *GetData() const   { return wx_static_cast(MyClassRefData*, m_refData); }
- @endcode
-
- in fact, all times you'll need to read the data from your wxObject-derived class,
- you'll need to call such function.
- Very important, all times you need to actually modify the data placed inside your
- wxObject-derived class, you must first call the wxObject::UnShare
- function to be sure that the modifications won't affect other instances which are
- eventually sharing your object's data.
-
- */
 
 
+@section overview_refcount_destruct Object Destruction
+
+When a COW object destructor is called, it may not delete the data: if it's
+shared, the destructor will just decrement the shared data's reference count
+without destroying it. Only when the destructor of the last object owning the
+data is called, the data is really destroyed. Just like all other COW-things,
+this happens transparently to the class users so that you shouldn't care about
+it.
+
+
+@section overview_refcount_list List of Reference Counted Classes
+
+The following classes in wxWidgets have efficient (i.e. fast) assignment
+operators and copy constructors since they are reference-counted:
+
+@li #wxAcceleratorTable
+@li #wxAnimation
+@li #wxBitmap
+@li #wxBrush
+@li #wxCursor
+@li #wxFont
+@li #wxIcon
+@li #wxImage
+@li #wxMetafile
+@li #wxPalette
+@li #wxPen
+@li #wxRegion
+@li #wxString
+@li #wxVariant
+@li #wxVariantData
+
+Note that the list above reports the objects which are reference counted in all
+ports of wxWidgets; some ports may use this technique also for other classes.
+
+
+@section overview_refcount_object Making Your Own Reference Counted Class
+
+Reference counting can be implemented easily using #wxObject and
+#wxObjectRefData classes. Alternatively, you can also use the
+#wxObjectDataPtr<T> template.
+
+First, derive a new class from #wxObjectRefData and put there the
+memory-consuming data.
+
+Then derive a new class from #wxObject and implement there the public interface
+which will be seen by the user of your class. You'll probably want to add a
+function to your class which does the cast from #wxObjectRefData to your
+class-specific shared data. For example:
+
+@code
+MyClassRefData* GetData() const
+{
+    return wx_static_cast(MyClassRefData*, m_refData);
+}
+@endcode
+
+In fact, any time you need to read the data from your wxObject-derived class,
+you will need to call this function.
+
+@note Any time you need to actually modify the data placed inside your wxObject
+derived class, you must first call the wxObject::UnShare function to ensure
+that the modifications won't affect other instances which are eventually
+sharing your object's data.
+
+*/
+

docs/doxygen/overviews/referencenotes.h

@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        referencenotes
+// Name:        referencenotes.h
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
@@ -8,25 +8,24 @@
 
 /*!
 
- @page referencenotes_overview Notes on using the reference
+@page overview_referencenotes Notes on Using the Reference
 
- In the descriptions of the wxWidgets classes and their member
+In the descriptions of the wxWidgets classes and their member functions, note
- functions, note that descriptions of inherited member functions are not
+that descriptions of inherited member functions are not duplicated in derived
- duplicated in derived classes unless their behaviour is different. So in
+classes unless their behaviour is different. So in using a class such as
- using a class such as wxScrolledWindow, be aware that wxWindow functions may be
+wxScrolledWindow, be aware that wxWindow functions may be relevant.
- relevant.
- Note also that arguments with default values may be omitted from a
- function call, for brevity. Size and position arguments may usually be
- given a value of -1 (the default), in which case wxWidgets will choose a
- suitable value.
- Most strings are returned as wxString objects. However, for remaining
- char * return values, the strings are allocated and
- deallocated by wxWidgets. Therefore, return values should always be
- copied for long-term use, especially since the same buffer is often
- used by wxWidgets.
- The member functions are given in alphabetical order except for
- constructors and destructors which appear first.
 
- */
+Note also that arguments with default values may be omitted from a function
+call, for brevity. Size and position arguments may usually be given a value of
+-1 (the default), in which case wxWidgets will choose a suitable value.
 
+Most strings are returned as wxString objects. However, for remaining char *
+return values, the strings are allocated and deallocated by wxWidgets.
+Therefore, return values should always be copied for long-term use, especially
+since the same buffer is often used by wxWidgets.
+
+The member functions are given in alphabetical order except for constructors
+and destructors which appear first.
+
+*/