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
- @ref refcountequality_overview
- @ref refcountdestruct_overview
- @ref refcountlist_overview
- @ref object_overview
+@li @ref overview_refcount_ignore
+@li @ref overview_refcount_equality
+@li @ref overview_refcount_destruct
+@li @ref overview_refcount_list
+@li @ref overview_refcount_object
 
 
- @section refcount Why you shouldn't care about it
+<hr>
+
+
+@section overview_refcount_ignore Why You Shouldn't Care About It
+
+Many wxWidgets objects use a technique known as <em>reference counting</em>,
+also known as <em>copy on write</em> (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).
 
- 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
+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.
+@section overview_refcount_equality Object Comparison
+
+The == and != operators of the reference counted classes always do a @c deep
+comparison. This means that the equality operator will return @true if two
+objects are identical and not only if they share the same data.
+
+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.
+
 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.
+#wxObject derived classes, you should not use the == and != operators but
+rather the wxObject::IsSameAs function.
 
 
- @section refcountdestruct Object destruction
+@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. As for all other COW-things, this happens transparently to the class users so
- that you shouldn't care about it.
+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 refcountlist List of reference-counted wxWidgets classes
+@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:
- #wxAcceleratorTable
+The following classes in wxWidgets have efficient (i.e. fast) assignment
+operators and copy constructors since they are reference-counted:
 
- #wxAnimation
+@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
 
- #wxBitmap
+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.
 
- #wxBrush
 
- #wxCursor
+@section overview_refcount_object Making Your Own Reference Counted Class
 
- #wxFont
+Reference counting can be implemented easily using #wxObject and
+#wxObjectRefData classes. Alternatively, you can also use the
+#wxObjectDataPtr<T> template.
 
- #wxIcon
+First, derive a new class from #wxObjectRefData and put there the
+memory-consuming data.
 
- #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.:
+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); }
+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.
+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
- functions, note that descriptions of inherited member functions are not
- duplicated in derived classes unless their behaviour is different. So in
- using a class such as wxScrolledWindow, be aware that wxWindow functions may be
- 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.
+In the descriptions of the wxWidgets classes and their member functions, note
+that descriptions of inherited member functions are not duplicated in derived
+classes unless their behaviour is different. So in using a class such as
+wxScrolledWindow, be aware that wxWindow functions may be 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.
 
 */
 
-