Clearify documentation on config groupsaver and give a small code example

1 files changed, 9 insertions, 0 deletions

diff --git a/libopie2/opiecore/oconfig.h b/libopie2/opiecore/oconfig.h
index 8c3060c..ab95dc3 100644
--- a/libopie2/opiecore/oconfig.h
+++ b/libopie2/opiecore/oconfig.h
@@ -1,28 +1,29 @@
 /*
                              This file is part of the Opie Project
 
                              (C) 2003 Michael 'Mickey' Lauer <mickey@tm.informatik.uni-frankfurt.de>
+
                              Inspired by the config classes from the KDE Project which are
               =.             (C) 1997 Matthias Kalle Dalheimer <kalle@kde.org>
             .=l.
            .>+-=
  _;:,     .>    :=|.         This program is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This program is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
@@ -87,48 +88,56 @@ private:
  *
  * Careful programmers always set the group of a
  * @ref OConfig object to the group they want to read from
  * and set it back to the old one of afterwards. This is usually
  * written as:
  * <pre>
  *
  * QString oldgroup config()->group();
  * config()->setGroup( "TheGroupThatIWant" );
  * ...
  * config()->writeEntry( "Blah", "Blubb" );
  *
  * config()->setGroup( oldgroup );
  * </pre>
  *
  * In order to facilitate this task, you can use
  * OConfigGroupSaver. Simply construct such an object ON THE STACK
  * when you want to switch to a new group. Then, when the object goes
  * out of scope, the group will automatically be restored. If you
  * want to use several different groups within a function or method,
  * you can still use OConfigGroupSaver: Simply enclose all work with
  * one group (including the creation of the OConfigGroupSaver object)
  * in one block.
  *
+ * \code
+ * OConfigGroupSaver saver(cfg,"TheGroupThatInWhat");
+ * \endcode
+ *
+ * Note that OConfigGroupSaver (cfg,"TheGroupThatInWhat"); would get imediately
+ * destructed after created and that you would save in the old group which
+ * is unwished.
+ *
  * @author Matthias Kalle Dalheimer <Kalle@kde.org>
  * @version $Id$
  * @see OConfig
  */
 
 class OConfigGroupSaver
 {
   public:
     /**
      * Constructor.
      * Create the object giving a @config object and a @a group to become
      * the current group.
      */
     OConfigGroupSaver( OConfig* config, QString group ) :_config(config), _oldgroup(config->group() )
         { _config->setGroup( group ); }
 
     OConfigGroupSaver( OConfig* config, const char *group ) :_config(config), _oldgroup(config->group())
         { _config->setGroup( group ); }
 
     OConfigGroupSaver( OConfig* config, const QCString &group ) : _config(config), _oldgroup(config->group())
         { _config->setGroup( group ); }
     /**
      * Destructor.
      * Restores the last current group.